Manual for Brand Partners: Icecat Push-API (API-IN)

Version: 3.2
Updated on: October 6rd, 2026

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 and Category. The international product name is taken from the Product Code. Readable names are added afterwards, per language, as Product Model Names.
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.

Version	Base URL	Parameter Format
v1	/rest/	snake_case
v2	/restful/v2/	snake_case
v3	/restful/v3/	camelCase

💡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)

Field	Required	Explanation
Category	Yes	Every product must have a CategoryId.
• Defines the product type
• Determines available specifications
• Must be a leaf (lowest-level) category
👉 This is the most important field. If incorrect, the product structure will be wrong.
Virtual category	No	Additional grouping layer used for segmentation.
Example: Category: Laptops → Virtual Category: Ultrabooks
Use when you need extra grouping beyond the main category.
Do not use when category already fully describes the product.
Family	Sometimes	Represents a product line within a brand.
Example: Brand: HP → Family: Pavilion
Use when product belongs to a known product line
💡Important! Some brands require Family. Check IsFamilyMandatory (see Getting Started).
Series	No	Subgroup within a Family.
Example: Family: Pavilion → Series: Gaming
Use when product has a defined sub-line.
Skip when no series exists

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. GTIN (Product Identifiers)

A GTIN is the barcode number that identifies your product in trade – an EAN, a UPC, or the longer case code. It carries no locale in Icecat: the same number is used in every market, and one product may carry several GTINs.

What to know before you start:

• Icecat accepts 8, 12, 13 and 14 digits. Shorter codes are stored padded with leading zeros to 13, so 12345670 comes back as 0000012345670.
• The last digit has to be the correct GS1 check digit, and the number may not be all zeros.
• A GTIN belongs to one product at a time. Submitting one that currently sits on another product takes it off that product and attaches it to yours.
• A GTIN is confirmed for export by default. Confirming is one-way – if a number turns out to be wrong, remove it rather than trying to hide it.

🔍Full manual: Manual for Brand Partners: Icecat Product GTINs – reading what GTINs a product has, adding and updating GTINs in bulk, the three batch policies, confirming, removing, every limit and every error message.

2. Product Gallery

Gallery is the set of product images shown for a product. It supports both International (INT) and Local images.

The gallery is the one asset with a service of its own. It does not live under bo.icecat.biz: every gallery request goes to https://api.icecat.biz/product-gallery/v1/… and answers in a different shape from the rest of the Brand API.

SCOPE	DESCRIPTION
INT	Image available for all languages
Local	Image specific to a language (requires LanguageId)

What to know before you start:

• Accepted formats: jpeg, png, tiff, bmp, webp. The format is read from the file, not from the extension.
• Each side between 200 and 10 000 pixels; up to 50 MB.
• isPrivate restricts an image to the channel partners authorised for your brand in the Icecat system. It is allowed only in the Icecat gallery.
• expiryDate is a day, not a moment, and it has to be in the future.
• A brand account does not delete images — it deactivates them, which is reversible.

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

🔍 Full manual: Manual for Brand Partners: Icecat Gallery API – the address, the model, ordering, partner galleries, pushing a whole gallery in one call, and the errors this service answers with.

🔍 Already pushing images through the old Gallery endpoints? Start with Manual for Brand Partners: Migrating a Gallery Integration to the Icecat Gallery API.

3. Product Multimedia

Multimedia is everything that travels with a product but is not a picture: videos, 360 spins, manuals, leaflets, energy labels, safety sheets and the regulatory documents.

SCOPE	DESCRIPTION
INT	Shared across all languages
Local	Specific to a language (requires LanguageId)

What to know before you start:

• Eleven asset types are open to a brand account: 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. The type is a fixed string and has to match exactly.
• Whether an asset may be international is decided by its type, not by you. An EU Energy Label, for one, is international only.
• Documents with no type of their own — Quick Start Guide, Carbon Footprint, CE Marking, declarations of conformity and the rest — are pushed as other digital assets and told apart by their short description.
• A brand account does not delete multimedia — it deactivates it, which is reversible.

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

🔍 Full manual: Manual for Brand Partners: Icecat Product Multimedia – the asset types and their file formats, the recognised document captions, pushing one object and pushing a set, the queue, the limits and the error messages.

4. Product Model Name

The model name is the short designation that identifies the product — what a partner shows as the product’s name on the page and in a listing. It is Local content: one name per locale, in each of the locales your account is assigned.

What to know before you start:

• A brand account cannot create, change or remove the International model name (LanguageId: 0).
• A product created by a brand account takes its product code as the International name, so that field shows something like 20U9005MGE until an Icecat editor replaces it.
• A market with no local name of its own receives the International one, product code included.
• One name per locale: writing again replaces it. Up to 3000 characters, one line, not blank.

🔍Full manual: Manual for Brand Partners: Icecat Product Model Name – reading, setting one locale, setting several in one call, removing a locale, the limits and the error messages.

5. Product 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

Scope	Description
Local	Language-specific description (requires LanguageId)

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. Product 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. Product 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.

Scope	Description
Global	International values (e.g., “5000 mAh”, “Intel Core i7”) that apply to all markets.
Local	Language-specific values or translations for features that require localization.

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. Product 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