Manual for Icecat Push-API (API-IN)

version: 3.0

This manual explains how brand users can use Icecat’s Brand API (Push API) to create, update, and manage product content in Icecat Brand Cloud automatically.

Use this API when you want to synchronize product data from your own system, PIM, or integration flow into Icecat without manual editing in the Icecat Brand Cloud interface.

With the Brand API, you can manage the main product record, product identifiers, publication settings, localized content, images, multimedia, specifications, bullet points, reasons to buy, and related products.

How the API Works (Core Concepts)

This section explains the key concepts behind the Brand API. Understanding these concepts will help you use the API correctly and avoid common mistakes.

Product as a Central Entity

In Icecat, a Product is the main object that all data is attached to.

A product contains:

• Identifiers – Brand, Category, Product Code (PartCode), GTIN
• Content – descriptions, images, specifications, bullet points, multimedia
• Distribution settings – Publish status and access restrictions

All API operations are performed either on the product itself, or on data linked to a specific product.

Content Types: International vs Local

Icecat separates product content into two types:

• International (INT) Content: language-independent, shared across all countries and languages, and defined once and reused everywhere.

Examples: GTINs, product images (global), product relations (can also be localized), lifecycle dates (can also be localized).

• Local Content: language-dependent, defined per language (locale), and used for market-specific presentation.

Examples: product descriptions, bullet points, reasons to buy, and localized images (if applicable).

💡Important! When working with the API, always check whether the data you are sending is INT (global) or Local (locale/language-specific). Sending data to the wrong scope may result in missing or incorrectly distributed content.

Product Visibility and Access

Product visibility is controlled by the Publish setting.

Publish values:

• Yes: Product is accessible by all channel partners via Icecat.
• Limited: Product is available only to authorized partners.
  When using Limited:
  • You can define which partners have access to the product
  • If no partners are assigned, the product behaves like Publish = No
• No: Product is not accessible to any partner.

Publication Date vs Release Date

These are different concepts:

• Publication Date controls when the product becomes visible in Icecat and used for scheduling availability.
• Release Date is a business information about when the product is launched on the market which partially control visibility.

Minimal Workflow

A typical integration follows this sequence:

1. Authenticate: Create a session or use an API token
2. Create Product: Provide basic data about Product Code, Brand, Category, and Model Name
3. Add Content: Provide descriptions, images, specifications, and other data
4. Set Visibility: Define Publish status (Yes / Limited / No)
5. (Optional) Configure Access: Assign specific partners if using Limited access

Authentication

Before you can send any data to the Icecat Brand API, you must authenticate your requests.

There are two supported methods:

• Session-based authentication (SessionId / AccessKey)
• API token (recommended for integrations)

💡 Security recommendation
We recommend enabling two-factor authentication (2FA) for your Brand Cloud account to improve security.
If 2FA is enabled, you must include a 2FAKey when creating a session.
Learn how to enable 2FA.

Authentication Overview

Every API request must include a valid authentication key.

Depending on the method you use:

• Session-based
  • You generate a SessionId
  • You pass it as AccessKey in each request
• API token
  • You use a permanent token
  • You pass it in the request header

Option 1: Session-Based Authentication

Use this method when working with the API manually (e.g., Postman) or for short-lived integrations.

Authentication is done by creating a SessionId, which must be included in all subsequent requests as an AccessKey.

1. Create a Session
2. Use SessionId in Requests by appending it as a parameter.

Option 2: API Token Authentication (Recommended)

Use this method for production integrations and automated workflows.

Instead of creating a session, you authenticate requests using a permanent API token.

Step 1: Obtain an API Token

To use this method, you need an API token assigned to your account.

If you do not have one, please contact your Icecat account manager.

Step 2: Use API Token in Requests

Include the API token in every request as a header: api-token: your_api_token

Example

wget --method GET \
  --header 'api-token: your_api_token' \
  <https://bo.icecat.biz/restful/v3/Product/123456>

Important Behavior

• API token is not tied to IP address
• No session creation is required
• Token remains valid until revoked

Supported Operations

API token authentication is supported for the following data operations:

• Product
• Specs / Features
• Multimedia
• Descriptions
• Bullet Points
• Gallery
• Product Relations

API Versions & Naming Conventions

Icecat API uses multiple versions. Different endpoints may use different versions and parameter naming styles.

💡Important! Always use the exact endpoint version shown in examples. Do not mix parameter formats between versions

• v2 → access_key, session_type
• v3 → AccessKey, SessionType

Product Structure & Taxonomy Alignment

This section explains how to structure your product correctly and ensure your data aligns with Icecat taxonomy.

Product structure and taxonomy directly affect how your product is categorized, which specifications can be applied, and how your product is found and displayed by partners.

Incorrect structure or misaligned data may result in rejected values, missing specifications, or poor product visibility.

Icecat Taxonomy Basics

Before uploading product data to Icecat, you must ensure that your data aligns with the Icecat taxonomy. This is a critical step — incorrect or misaligned data will lead to failed requests, rejected values, or improperly structured product content.

What is Icecat Taxonomy

Icecat organizes product data using a structured taxonomy consisting of:

• Categories – define the product type (e.g., Laptops, Computer Monitors)
• Features (Specifications) – define product attributes (e.g., Screen size, Processor model)
• List of Values (LOVs) – predefined allowed values for specific features (e.g., “Intel”, “AMD”)

All product data must follow this structure.

When uploading product data to Icecat:

• Your data must match existing categories, features, and values
• Free-form or custom values are not always allowed
• Some fields accept only predefined values (LOVs)

Classification Fields (How to Structure a Product)

How to Choose Classification (Recommended Flow)

1. Select correct Category
2. Check if Family is mandatory
3. Add Family (if required or relevant)
4. Add Series (if available)
5. Add Virtual Categories (only if useful)

When Adaptation is Required

You may need to adapt your data in the following cases:

1. Category mismatch

Your internal category does not match an Icecat category.

Example:

• Your system: “Ultrabooks”
• Icecat: “Laptops” (with optional Virtual Category)

👉 You must map your category to the closest Icecat category.

2. Missing Feature

Your product contains an attribute that does not exist in Icecat.

Example:

• Your data: “AI acceleration support”
• Icecat: no such feature available

👉 You may need to request a new feature.

3. Value not in LOV

Your value is not part of the predefined list.

Example:

• Allowed: “Black”, “Silver”
• Your value: “Graphite Black”

👉 You must:

• either map it to an existing value
• or request a new value

What You Should Do

To ensure successful data integration:

1. Check existing taxonomy: Use reference files to understand available categories, features, and values.
2. Reuse existing values whenever possible: Avoid creating variations of the same value, and keep data consistent.
3. Map your internal data: Align your categories and attributes to Icecat structure.
4. Request extensions when needed: Contact Icecat to add new features or extend value lists.

Reference Files

To explore the available taxonomy, use: 🔍 Manual for Reference Files XML

These files contain category structures, feature definitions, and allowed values.

💡Important! Incorrect taxonomy usage is one of the most common causes of API errors. Data that does not match Icecat structure may be rejected, ignored, or lead to incomplete product content.

Result

After aligning your data with Icecat taxonomy, you can safely:

• create products
• add specifications
• ensure consistent and correct data distribution

Getting Started: Required Data & IDs

Before creating or updating products, you need to retrieve a small set of reference data from Icecat. These values are required in almost all API requests and must be used as-is.

This section guides you through the first API calls you should make after authentication.

To work with the API, you will need:

• Brand IDs – to identify which brand you are allowed to manage
• Category IDs – to correctly classify your products
• Language IDs – to add localized content
• User ID – to identify you as the product owner when creating or updating products
• Optional:
  • Virtual Category IDs – to assign additional product grouping
  • Family IDs – to define the product line within a brand
  • Series IDs – to specify a subgroup within a family

Helpers

1. Get Your Assigned Brands
2. Get Categories
3. Get Your Languages
4. Get Your Account Data
5. Get Virtual Categories (Optional)
6. Get Families (Optional)
7. Check if Family is Mandatory
8. Get Series (Optional)
9. Get Countries

💡Important!

• Use only values returned by the API
• Do not hardcode IDs
• If unsure, start with: BrandId, CategoryId, and UserId

Result

After completing these steps, you are ready to:

• create a product
• add content
• manage product visibility

Product Management (Create & Update Products)

This section explains how to create and update the main product record in Icecat.

The Product is the central entity — all content (descriptions, images, specs) is attached to it.

Typical workflow:

1. Check if product already exists
2. Create product (if not found)
3. Verify product
4. Update product properties (if needed)

Key Tips

• Always check product existence before creating
• Start with minimal data, then enrich
• Do not guess Category — choose carefully
• Add classification fields only when confident

Result

After completing this step, you have:

• a valid product record
• a ProductId
• a base for adding content

Content Management (INT & Local Content)

After creating a product, you enrich it with content such as descriptions, images, specifications, and marketing data.

Icecat separates content into two types:

• International (INT) – shared across all markets
• Local – specific to a language (locale)

Key Rules:

• Do not use INT fields for localized content
• Always specify LanguageId for local data
• Provide content only for languages you are assigned to
• Missing local content = incomplete product presentation

1. International (INT) Content – GTIN (Product Identifiers)

GTIN is one of the main unique product identifier (EAN/UPC). A product may have multiple GTINs.

When to use:

• Always add GTIN if available
• Required for product matching and distribution

Rules and validation:

• Icecat supports GTIN with 8, 12, 13, or 14 digits.
• GTIN-12 is standardized to GTIN-13 by adding a leading 0.
• GTIN must pass checksum validation.
• One GTIN cannot belong to multiple products.
• is_exported = false means the GTIN is not validated and is not shared with channel partners.
• is_exported = true means the GTIN is available for export.
• Once is_exported is set to true, it cannot be changed back to false; use Delete GTIN instead.

Flow

1. Get Product GTINs
2. Create Product GTIN
3. Update GTIN / Confirm GTIN
4. Delete GTIN

2. International & Local Content – Gallery

Gallery is a set of product images displayed for a product. It supports both International (INT) and Local (language-specific) images.

Images are a key part of product presentation and are used across Icecat channels, exports, APIs, and partner platforms.

Read more about Gallery best practices here: 🔍 How to Make the Product Gallery Great Again

Rules and validation:

• Gallery supports both INT and Local images
• Local images require LanguageId
• Image must be accessible through a valid URL
• Supported formats: jpeg, png, tiff, bmp, x-windows-bmp, x-ms-bmp, webp
• Minimum image resolution: 200 × 200 px
• Maximum image resolution: 10,000 × 10,000 px
• Maximum image size: 50 MB
• Images can be marked Private (IsPrivate=true) and become available only to authorized channel partners
• Images can have an ExpirationDate, after which they are unavailable
• The same image may have multiple locale entries (Locales) with different GalleryId and LanguageId
• Avoid duplicate images for the same language

Check API Swagger here: 🔍 Swagger schema

Flow

1. Get Gallery
2. Create Gallery Image
3. Create Locale for Existing Image
4. Update Gallery Image
5. Delete Gallery Image

3. International & Local Content – Multimedia

Multimedia includes videos and documents that can be either global (INT) or language-specific (Local).

Use Multimedia for:

• product videos
• documents (manuals, datasheets, certificates)

Read more about all available Multimedia objects in Icecat here: 🔍 Multimedia overview

Rules and validation:

• Multimedia can be global (INT) or localized (Local)
• Local multimedia requires LanguageId
• Asset must be accessible via valid URL
• Supported types depend on configuration (EU Product Fiche, EU Energy Label, UK Energy Label, leaflet, manual pdf, other digital assets, video/mp4, 360, Safety Data Sheet, Size Chart, Repairability index overview)
• Avoid duplicates
• Use Local multimedia if content is language-specific

Check API Swagger here: 🔍 Swagger schema

Flow

1. Get Multimedia
2. Create Multimedia
3. Update Multimedia
4. Delete Multimedia

4. Local Content – Product Model Name

Product Model Name is a short model designation used to identify the product.

It is language-dependent (Local content) and can be managed per locale.

Product Model Name is used in product presentation and exports across Icecat channels.

Rules and validation:

• Product Model Name is Local content only
• International Product Model Name (langId=0) cannot be created, updated, or deleted by Brand users
• Product Model Name requires LanguageId
• Users can work only with languages they are authorized to manage
• Product Model Name must not be empty
• Maximum length: 3000 characters
• One Product Model Name per language is allowed

Flow

1. Get Product Model Names
2. Create Product Model Name
3. Update Product Model Name

5. Local Content – Descriptions

Descriptions contain product marketing, informational, legal, and SEO content used across Icecat channels.

Use Descriptions for:

• short product marketing text
• detailed product presentation
• warranty information
• official product URLs
• SEO metadata
• legal disclaimers

Supported description fields:

• ShortDescription – full product name
• MiddleDescription – short localized promotional description
• LongDescription – detailed product localized description
• OfficialUrl – official product page URL
• WarrantyInfo – warranty information
• SeoTitle – SEO title
• SeoDescription – SEO meta description
• SeoKeywords – SEO keywords
• Disclaimer – legal or explanatory notes

Rules and validation:

• Descriptions are Local content only
• Descriptions require LanguageId
• Users can work only with languages they are authorized to manage
• Different description fields may be populated independently
• Empty values are not allowed for creation/update operations where content is expected
• Use localized descriptions for market-specific messaging

Flow

1. Get Descriptions
2. Create Description
3. Update Description
4. Delete Description

6. Local Content – Bullet Points

🔍 Swagger schema

Bullet Points represent the unique selling points or key features of a product. They are designed to provide concise, easy-to-read highlights that distinguish the product from others in the same category.

Historically, this data was part of the marketing text, but it is now a standalone asset to allow retailers and channel partners to apply custom formatting and better display the product’s core benefits.

Use Bullet Points for:

• Unique Selling Points
• Key product highlights and benefits
• Concise features that require high visibility
• Information that shouldn’t be buried in long marketing descriptions

What to do

• Aim for 5–10 bullet points per product. While the system allows more, retailers typically optimize their layouts for this range.
• Do not duplicate information already present in the technical specifications. Bullet points should focus on benefits (e.g., “All-day battery life”) rather than just specs (e.g., “5000mAh battery”).
• Keep each bullet point concise (ideally under 150 characters) to ensure they remain readable on mobile devices.

Flow

1. Get BulletPoints
2. Create BulletPoint
3. Update BulletPoint
4. Delete BulletPoint

7. International & Local Content – Specs / Features

Features, also known as Technical Specifications, are the structured data points that define a product’s technical capabilities. Unlike marketing text, these are standardized across the Icecat taxonomy to allow for precise filtering, side-by-side comparisons, and automated title generation on retailer websites.

Specs are organized into Feature Groups (e.g., “Processor”, “Memory”, “Network”) to ensure a logical flow of information on the product page.

Features Taxonomy

• Mandatory Features: Some categories have “Mandatory” specs. A product cannot reach “Icecat Quality” status without these values.
• Searchable Features: High-priority specs are used by retailers for sidebar filters. Ensuring these are filled directly impacts your product’s findability.
• Feature types: Icecat supports many types as numerical, text, dropdown, etc. They are described in Create Value for Product Feature.

Flow

1. Get Product International Features
2. Get Product Local Features
3. Create Value for Product Feature
4. Update Value for Product Feature
5. Delete Value for Product Feature
6. Create a Restricted Value for Product Feature

8. Reasons to Buy

🔍 Swagger schema

Reasons to Buy (RTB) are promotional selling points displayed on product pages to help consumers understand product benefits at a glance. They consist of short title-and-text pairs, often accompanied by icons, and can be grouped for better visual presentation.

In the API and database, this asset is often referred to by its legacy name: Product Bullet.

• Components: Each RTB item includes a Title (mandatory), a Description/Value (optional), and an Icon URL (optional).
• Multiplicity: You can add multiple RTB items per product per language (1-to-many relationship).
• Sorting: Use the no parameter to define the display order within a group.
• De-duplication: The system automatically de-duplicates items based on a combination of Title + Value.

Recommendations

• Aim for 5–10 Reasons to Buy per product. While the system supports more, retailers typically optimize their layouts for this range.
• Never provide a value (description) without a title. A title-only RTB is allowed, but a description-only one is not.
• Keep titles concise (under 60 characters) and descriptions punchy. RTBs are meant for quick scanning, not long-form reading.
• Use high-quality, transparent PNG icons (recommended size: 128x128 px). Icons significantly improve the visual engagement of the product page.

Flow

1. Get Reasons to Buy
2. Create Reason to Buy
3. Update Reason to Buy
4. Delete Reason to Buy

9. Related Products

🔍 Swagger schema

Related Products define the static relationships between different items in the catalog to facilitate cross-selling, up-selling, and the discovery of compatible accessories or consumables. These links ensure that when a customer views a main product, they are presented with relevant additions (e.g., a printer showing compatible ink cartridges).

These relationships work both ways, though a product cannot be linked to itself.

• Identification: You can relate products using their IcecatID, EAN/UPC, or Product Code.
• Recommended by Brand: This is a premium relationship type where the brand explicitly endorses a product as a “top pick.”
• Recommended by Brand Duration: You can set an optional start and end date for brand recommendations (e.g., for seasonal campaigns).
• Permissions: Brand users can only create relations for products belonging to their own brand and within their assigned locales.

Flow

1. Get Product Static Relations
2. Create Product Static Relation
3. Create Batch of Product Static Relations
4. Delete Product Static Relation
5. Create a new Locale for Product Static Relation
6. Update Product Static Relation Locale
7. Delete Product Static Relation Locale

Product Access Management

1. Product Life Cycle: Release & End of Life Dates

Release Date – the date when this product is expected to be released to the market.

End of Life Date – the date when the product is no longer available on the market.

The time between Release and End of Life dates is called Product Life Cycle. During that time the product is available to all channel partners.

Channel partners authorized by the brand (see Assigned Resellers section) can access product data anytime, regardless of Life Cycle.

LifeCycle dates can be International or Local – different for each country.

Flow

1. Get Product Life Cycle
2. Create Product LifeCycle
3. Update Product LifeCycle
4. Delete Product LifeCycle

2. Publication Dates

As a brand user, you can either allow product access to all resellers or only to a special group of manually approved users.

The Publish dropdown accepts the following values:

• Yes – opens product to all resellers via Icecat portal, API endpoints and export files.
• No – product data is not accessible to any reseller.
• Limited – product data is provided to manually selected assigned resellers. You can set the users which have access to the product in the Accessible By select.

The Publish value could also be set to a certain date. This is done with ProductPublicationDate rest, described below.

⚠️ Publication Date ≠ Release Date.

Not released product is available to assigned resellers.

Not published product is not available to anyone.

Product Publish is set managed during the creation, use Get Product General Data to read the status and Update Product General Property to update it.

Flow

1. Get All Product PublicationDates
2. Create Product PublicationDate
3. Get Product PublicationDate by ID
4. Update Product PublicationDate by ID
5. Delete Product PublicationDate by ID

3. Assigned Reselllers

The user must be an assigned reseller of your Brand if you wish to grant them access to the Product with Limited access.

If you want to authorize a certain reseller to your Brand, please contact your Icecat account manager.

If you set the property AccessibleBy to SelectedResellers for a product and do not authorize any user it  will be fully restricted for all users as if you have set Publish=No.

1. Get Assigned channel partners for a Brand
2. Get AssignedResellers for the Product
3. Update Assigned Resellers for the Product
4. Delete Assigned Resellers for the Product