Manual: How to Import Free Product Content Into Your E-commerce System via Icecat API

This guide is intended for developers working with Icecat via API. The document provides an overview of each Pull API, used by channel partners to download the Icecat Product Data Sheets.

If you have the brand account, which updates the product data on Brand Cloud, refer to Push API Manual instead.

Subscriptions

Icecat provides a Free Open Icecat subscription with access to the Open Icecat repository.

The Open Icecat repository is the part of the Icecat XML repository that is sponsored by Brands and is provided for free to the channel. The most recent list of Open Icecat brands is here.

Open Icecat is also useful for testing purposes before you upgrade to Full Icecat. The technical structures are 100% compatible with those of Full Icecat.

However attractive the free Open Icecat database is, the Full Icecat database still contains many, many more brands: tens of thousands. Datasheets are often provided with service levels and coverage guarantees.

In case you want to upgrade to Full Icecat, please contact us via the contact form or click on the Upgrade in your Settings.

Read more: Main advantages of Full Icecat over Open Icecat

Open Icecat Fair use Policy

We require any user of Open Icecat product data – in a free Open Icecat subscription or as part of the Full Icecat data – to respect the Open Icecat Fair Use Policy.
Explicitly relevant for website development is:

• to mention explicitly the “Specs Icecat” on all product datasheets, with a link to Icecat.biz.
• to include explicitly an AS IS Disclaimer, an example of which is here: English Disclaimer.
• to not use any Icecat data for AI training.

Recommendation on Automations

1. Download the Icecat Catalog using the Index files.
2. files.index for all products in Icecat. Use this index once at the start of setting up the onboarding for Icecat.
3. daily.index.xml.gz for the daily new and updated products. Use this index daily to select new and updated products.
4. In order to import only certain products from the list we recommend filtering the products by:
   • Brand
   • Category
   • Quality
   • On market
   • Updated
5. Get the Identifiers to use them in Icecat API – GTINs, Product Codes, Brand Names
6. Fetch the relevant Product Data Sheets.

Taxonomy

During matching process you may notice that Icecat data heavily relies on IDs for the entities – Categories, Brands, Locales, etc.

In order to Match the names with the corresponding IDs, Icecat provides taxonomy in Reference Files.

• XML Reference files are the most developed and easy-to-use.
• CSV Reference files are not recommended as they are interconnected like an SQL table, therefore they are harder to use.
• JSON Reference files are not provided.

Anti-Rip Policy

After a rip of our general site, an IP address may be temporarily blocked (error 499). A rip is not acceptable as it may hurt site performance and can be a copyright infringement.

Maximum limitation is 100 requests per IP per second. We recommend keeping it on 50-70.

Access to Content

Basic Auth

To access Open Icecat, you will need a username and password provided by Icecat.

In JSON API for Basic Auth the username is used with an app_key instead of the password.

IP Whitelisting

In short, access to the product content of Full Icecat is protected. If you want to access Full Icecat product content, you must unlock your IP address.

• Fill in the IP address(es) of your server(s) and office in the Allowed IP addresses field.
• If you do not know your office IP addresses, visit What is my IP to find your (office) IP.
• For your server IP address, please ask your system operator or provider.
• You can fill in several IP addresses, separated by a space.
• You can whitelist 4 subnet masks using CIDR notation with the /24 prefix, for example: 152.168.1.0/24
• You can whitelst IP range, for example: 152.168.1.1-152.168.1.100

Dynamic Tokens

Dynamic tokens are secure tokens that are passed as headers and replaces both IP Whitelisting and Basic auth.

It is recommended way to fetch the data from Icecat. Learn more here: Access Tokens as an Alternative to IP Whitelists and app_key

API Overview

LiveHTML

Beautiful ready-to-use HTML pages with pre-defined design.

• The entire integration requires a single <script> tag and one JavaScript method call — no server-side rendering, no data parsing, no frame/iframe management.
• Immediate ready-to-use data is inserted directly into your HTML.
• Great integration with ProductStories – interactive, brand-authored mini-experiences (rich media, interactive layouts) embedded within product datasheets.
• Granular calls allows you to receive partial data to display them in different places of your website, allowig it to be included in your website.
• Supports multi-language fallback: pass ['en', 'fr'] and the API serves the first available locale.

AI Agent MCP

Especially for agentic AI, the Model Context Protocol (MCP) has become a de-facto standard.

Icecat supports MCP to be part of your AI experience and provide a analyzis with a reliable product data for context.

JSON

• The easiest pure data format to work with – JSON is modern and straightforward.
• The response is a predictable two-field structure (msg + data) with dot-navigable nested objects – no XML parsing libraries required, native to JavaScript, Python, PHP, and virtually any modern stack.
• The content parameter enables Granular Calls – fetch only the sections you need (e.g., content=essentialinfo,gallery,featuregroups) instead of the full datasheet, reducing payload size and parsing effort.
• All additional data (Multimedia, ProductStories, Reviews, Variants, Packaging, BrandOrganizations) is available out of the box – no need to request access from an account manager, unlike XML.
• Granular-only sections (packages, brandorganizations, analytics) expose EPR/sustainability data, brand legal entities, and download popularity that are not available in a standard full call.

XML

• The most sophisticated and deeply integrated API in Icecat.
• Compatible with XML Index Files and Reference Files (CategoriesList, FeaturesList, SuppliersList, MeasuresList) – build a complete local taxonomy mirror and join it with product data offline, something other APIs cannot replicate.
• International locale (lang=INT) is exclusive to XML – no other Icecat API supports it. A single INT request returns data for all locales activated in your account, eliminating the need to loop through languages one by one.
• MetaXML provides a lightweight “ping” response (almost equivalent to one row from files.index.xml) – use it to check product existence, last-updated timestamp, distributor stock, and mapped Product Codes without downloading the full datasheet.
• HEAD requests offer an even lighter existence check: 200 = product exists, 404 = doesn’t exist or credentials wrong – zero body parsing, ideal for bulk pre-filtering before full GET calls.
• The Last-Modified header on every response gives you a change-detection timestamp – compare it against your local cache to skip re-downloading unchanged datasheets, enabling efficient delta-sync pipelines.

⚠️ Access to additional fields (BrandOrganizations, Packages, Variants, Reviews) must be enabled by account managers — unlike JSON where everything is available out of the box.

⚠️ Authentication requires IP whitelisting + Basic Auth for Full Icecat (dynamic api_token also supported but does not work for MetaXML). Plan for this setup overhead in your integration timeline.

CSV

• CSV is flexible and easily convertable to tables.
• Multi-product call in a single request — unlike JSON and XML, the CSV API accepts comma-separated icecat_ids (URL-encoded as %2C), letting you batch-fetch many datasheets in one HTTP call without looping.
• Uses the same domain as the XML API (data.icecat.biz/xml_s3/xml_server3.cgi), so if you already have XML integration infrastructure, switching to CSV only requires changing the output parameter.
• Compatilbitlity with CSV Index Files, meaning you can automate a pipeline: download the index → extract icecat_ids → batch-fetch full datasheets via CSV in multi-product calls.
• Compatibility with CSV Reference Files.
• Personal Catalog File is based entirely on CSV API.
• Two response modes via the output param: productcsv (full datasheet — specs, descriptions, gallery, multimedia, variants) or richproductcsv (rich media only – multimedia, gallery, descriptions) — choose based on what you actually need to display.

⚠️ CSV is considered a legacy format – many assets and controls available in other APIs (partial data, relations limit, reviews, analytics, FeatureLogos, GeneratedPDF) are not supported in CSV – is best for bulk tabular exports or systems that only ingest flat files.

Icecat Identifiers Overview

All Icecat APIs use the same identifiers to locate the products:

• Locale
• Product Code
• Brand Name
• GTIN
• icecat_id
• category (optional)

Locale

Language (Locale) short identifier. The explanation could be found in the manual Language Table.

For XML integration, locales taxonomy is provided in LanguageList.xml.gz.

For CSV integration, the Reference file is language.txt.

Product Code

It’s a unique code assigned by Brands to identify each of their products. Think of it like a serial number for a specific product model.

Product Codes are unique only within a brand; therefore, for a correct request, a Brand name is always required for any API in Icecat.

A product might have many Product Codes, and different distributors often produce different Product Codes for the same product. To help you correct the Product Codes from many distributors and to help you to get the best coverage, we are publishing the available mappings along with the official Product Code.

Product Codes are always upper-case and may contain characters that must be URL-encoded. For instance, # needs to be replaced with %23. Other examples: @, &, =, etc.

Brand

Alternative names: Supplier, Vendor. Name of the brand of the requested product, for example Bosch or Lenovo. We log all Icecat product requests, which gives a product popularity indication, useful for sorting products and analyzing market trends. The brands are sorted by popularity here.

For XML integration, the full information about brands are provided in SupplierList.xml.

For CSV integration, the Reference file is supplier.txt.

GTIN

GTIN, EAN, or UPC code to identify a product. Further, it is referred to as GTIN because it’s a more general term that means a unique numeric product identifier. GTIN is unique within all Icecat repository, and hence you may search for the product with GTIN only.

A product might have more than one GTIN.

💡A single GTIN might be assigned to different products because Brands may reuse them. Only one product can have a certain GTIN at once.

It is important to note that a GTIN may change its association with products over time. This can happen due to directives from brands or actions taken by brand users in Icecat Cloud. To ensure accuracy and avoid any confusion, we recommend performing an extra check by verifying the combination of the GTIN and the Icecat product ID. This will help confirm that the GTIN has not shifted from one product to another.

Icecat ID

Icecat product ID, unique within the Icecat Repository, and a product can only have one ID.

Useful for testing, however, we do not recommend using it as a primary key because the GTIN and Product Code may sometimes be transferred to a different icecat_id.

For example, when one brand acquires another one, it may transfer the products.

Selected Assets from Icecat Datasheet

Unconfirmed GTINs

By default, we only provide access to GTINs, that are verified by our partners, so we can guarantee that the product is distributed in the country. However, if you wish to have access to all GTINs in Icecat, including unverified, please contact us.

Brand Organizations

• For XML integration, access to GPSR data has to be activated by your account manager.
• For JSON integration, it is available out of the box as a part of Granular Call.
• CSV API does not support BrandOrganizations in product data, instead they are provided in BrandOrganizations.csv

Packages

Also a part of EU regulations, packages are special type of product relations that provides unique codes for packaging under.

• For XML integration, access to packages in product data has to be activated by your account manager.
• For JSON integration, it is available out of the box as a part of Granular Call.
• CSV API does not support product packages at the moment.

Product Reviews

Are you interested in adding professional and real user reviews to your webshop? Then check out our review manual.

External Taxonomies

For our partners we provide access to exclusive multimedia and product data. Access to extertnal taxonomies needs to be activated by your account manager.

Add-ons

If you are searching for a way to connect your app and integrate Icecat product content, check the most popular Icecat Add-ons.