Manual for Channel Partners: Icecat Product JSON

Version: 3.0
Updated on: October 13th, 2026

This manual explains how to request the data sheet of one product in JSON: how to authenticate, which parameters to use, how to request only the parts you need, what each part of the response contains, which products you can and cannot receive, and which errors to expect. Use it if you build a web application, a webshop or a PIM that fetches Icecat product content in real time.

To compare Product JSON with the other ways of receiving Icecat content, see Manual for Channel Partners: How to Choose Your Integration with the Icecat Catalogue.

To find out which of your products Icecat covers and when their content changes, see Manual for Channel Partners: Personal Index File (PIF).

1. What Product JSON is

Product JSON returns the data sheet of one product per request, in real time. A data sheet contains, among other things:

• identifiers, titles, brand, category, product family and series;
• descriptions, bullet points, SEO texts, warranty information and disclaimers;
• specifications with their full structure: groups, order, units, raw and display values;
• the image gallery, documents, videos, 360° tours, energy labels and product stories;
• reasons to buy, feature logos, reviews, related products and variants.

You can request the whole data sheet, or only the sections you need, for example only the gallery or only the title (see section 5).

Product JSON returns one language per request. To receive a product in several languages, send one request per language.

2. When we recommend Product JSON

We recommend Product JSON when:

• You build a web application. JSON is read natively by JavaScript and by every modern programming language.
• You need only part of a data sheet. With a granular call you receive, for example, only the gallery or only the specifications, and nothing else.
• You want content in real time, at the moment you need it, product by product.

Product JSON is not the best choice when:

• You want all languages of your subscription in one data sheet. JSON has no INT data sheet. Use the Product XML for that.
• You want to show content on your pages without storing it. Use Icecat Live HTML.
• You need a list of products to fetch. Product JSON works one product at a time. Use the Personal Index File (PIF) or the XML Index Files to know which products to request (see section 10).

3. Before you start

1. Have a Channel Partner account. Requests from other account types are refused (error 3, see section 9).
2. Know your subscription.
   • Open Icecat covers the brands that sponsor Icecat.
   • Full Icecat covers all brands. The same request returns a product only when your subscription covers its brand (see section 8).
3. Create an API token and a content token. In MyIcecat, go to Access Tokens. See Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth.
   • The API token identifies your account. It is required for Full Icecat products, unless you use the app key. For Open Icecat products it is optional, but we recommend it for every request.The content token is added to the file links in the response, so that you can download the images, documents and videos you are entitled to.
   Treat both tokens like passwords: keep them on your server only, never in a web page or in JavaScript that runs in the shopper’s browser. You can create, revoke and replace them in MyIcecat at any time.
4. Plan to host the files yourself. Icecat is not a file host. Download the images, documents and videos from the response and serve them from your own storage. Do not link to Icecat file links from your shop pages: they can stop working. If you want Icecat content shown on your pages without storing it, use Icecat Live HTML.

An older authentication method, the app key, is still supported for existing integrations, but we do not recommend it. See App key.

4. Request

Address

https://live.icecat.biz/api

Only the GET method is supported.

Example

curl -H "api-token: <API_TOKEN>" -H "content-token: <CONTENT_TOKEN>" \
  "https://live.icecat.biz/api?lang=EN&icecat_id=56195846"

Without tokens, for an Open Icecat product, with the public demo account:

https://live.icecat.biz/api?lang=EN&shopname=openicecat-live&icecat_id=56195846

Headers

Send tokens as headers, not as parameters in the address.

App key (not recommended)

An older method, the app key, is still supported for Full Icecat products. We recommend the API token instead: it works from any server, and the secret never appears in the request address. Open Icecat products need no app key: shopname is enough.

Add app_key (also accepted: AppKey, appkey) and shopname to the request:

https://live.icecat.biz/api?lang=EN&shopname=<YOUR_USERNAME>&app_key=<APP_KEY>&icecat_id=<ICECAT_ID>

• The request must come from an IP address whitelisted in My Profile. Otherwise you get error 5.
• The app key must belong to the account in shopname. Otherwise you get error 7.
• The app key never expires. If it leaks, contact your account manager.

Parameters

Parameter names are case-sensitive. Write them exactly as below, or use one of the listed alternatives.

Send each parameter once, as a single value. A repeated parameter, or a parameter sent as a list (lang[]=EN), is refused with error 20.

Encode special characters. Product codes and brand names may contain characters such as #, &, +, / or spaces. URL-encode them, for example # as %23 and , as %2C.

Identifying the product

Use one of these:

• icecat_id;
• Brand + ProductCode;
• GTIN.

If you send more than one, Icecat uses them in this order:

1. icecat_id, when present, decides alone.
2. Brand + ProductCode. If you also sent a GTIN and no product matches brand and product code, Icecat tries the GTIN.
3. GTIN alone.

ProductCode and Brand are not case-sensitive. A GTIN may be sent with or without leading zeros.

A brand without a product code, or a product code without a brand, is not enough (error 4).

Prefer the Icecat product ID when you have it, for example from the PIF. Icecat has already matched the product, so differences in spelling can no longer cause a miss.

Language

Each request returns one language. When a text does not exist in that language, some parts of the data sheet fall back to another language: for example, specification names fall back to English, and the gallery and documents include files that are not language-specific. Check the Language field that comes with each text to know which language you received.

An empty Language means international content. Images, videos, documents and other files with an empty Language are not tied to one language: they apply to all languages. Use them, do not filter them out. Icecat has already selected the content that is relevant for the language you requested, so everything in the response belongs on your product page in that language.

5. Choosing what to receive: the content parameter

The whole data sheet

Leave content out, leave it empty (content=), or use content=all. You receive these sections: GeneralInfo, Image, Multimedia, Gallery, FeaturesGroups, FeatureLogos, ReasonsToBuy, Reviews, ProductRelated, CatalogObjectCloud, Variants, ProductStory, Dictionary.

Every section is always present, even when the product has no content for it. It is then an empty list [] or an empty object {}.

Granular call: only the sections you need

List the sections in content, separated by commas (%2C when encoded):

https://live.icecat.biz/api?lang=EN&shopname=openicecat-live&icecat_id=56195846&content=title%2Cgallery

Values are not case-sensitive.

An unknown value does not cause an error. You receive the sections you asked for correctly, plus a ContentErrors list that names the unknown value:

"ContentErrors": ["Not found: foo"]

Check ContentErrors after a granular call, so that a typo does not go unnoticed.

Example with all granular-only sections:

https://live.icecat.biz/api?lang=EN&shopname=openicecat-live&icecat_id=56195846&content=essentialinfo%2Cpackages%2Cbrandorganizations%2Canalytics

6. Response

6.1 The response envelope

A successful response has HTTP status 200:

{
  "msg": "OK",
  "data": {
    "GeneralInfo": {},
    "Image": {},
    "Multimedia": [],
    "Gallery": [],
    "FeaturesGroups": [],
    "FeatureLogos": [],
    "ReasonsToBuy": [],
    "Reviews": [],
    "ProductRelated": [],
    "CatalogObjectCloud": {},
    "Variants": [],
    "ProductStory": [],
    "Dictionary": {},
    "DemoAccount": false
  }
}

• msg is OK on success.
• data holds the sections you requested.
• DemoAccount is true when you use a public demo account (such as openicecat-live) without an API token, and false otherwise.
• ContentErrors appears only after a granular call with an unknown value (see section 5).

An error response has a different shape. See section 9.

Use links exactly as you receive them. Do not build links yourself and do not rely on how they are composed: their format can change at any time.

6.2 GeneralInfo

{
  "IcecatId": 56195846,
  "ReleaseDate": "",
  "EndOfLifeDate": "",
  "Title": "DELL G5 5587 Intel® Core™ i7 i7-8750H Laptop 39.6 cm (15.6\") Full HD …",
  "TitleInfo": {},
  "Brand": "DELL",
  "BrandID": "292",
  "BrandLogo": "https://…",
  "BrandInfo": {},
  "ProductName": "5587",
  "ProductNameInfo": {},
  "BrandPartCode": "5587-9709",
  "GTIN": ["5397184119709"],
  "Category": {},
  "ProductFamily": {},
  "ProductSeries": {},
  "Description": {},
  "SEOs": {},
  "SummaryDescription": {},
  "BulletPoints": {},
  "GeneratedBulletPoints": {},
  "GTINs": [],
  "VirtualCategory": []
}

IcecatId

The Icecat product ID. Use it as icecat_id in later requests.

ReleaseDate and EndOfLifeDate

When the product becomes available to Channel Partners, and when it is no longer on the market. Format DD-MM-YYYY. Empty when not known.

Title and TitleInfo

"Title": "Brand Family Series ProductName",
"TitleInfo": {
  "GeneratedIntTitle": "Brand Family Series ProductName",
  "GeneratedLocalTitle": { "Value": "Brand Family Series ProductName", "Language": "EN" },
  "BrandLocalTitle":     { "Value": "Brand Family Series Feature1 Feature2", "Language": "EN" }
}

Title is the best title for the requested language. TitleInfo shows all variants:

• GeneratedIntTitle: brand (+ family + series) + the international product name.
• GeneratedLocalTitle: the same, with the product name in the requested language. It can differ a lot from the international title, especially for non-Latin languages.
• BrandLocalTitle: brand (+ family + series) + selected specifications. Used as Title when the product has no product name in the requested language.

Brand, BrandID, BrandLogo and BrandInfo

"Brand": "LEGO",
"BrandID": "3479",
"BrandLogo": "https://…",
"BrandInfo": { "BrandName": "LEGO", "BrandLocalName": "", "BrandLogo": "https://…" }

• Brand: the brand name.
• BrandID: the Icecat brand ID. You can match it with the brand list in the Icecat reference files.
• BrandLogo: a link to the brand logo.
• BrandLocalName: the brand name in the requested language, usually for non-Latin languages. Empty when there is none.

ProductName and ProductNameInfo

"ProductName": "ホリデーキャンピングカー",
"ProductNameInfo": {
  "ProductIntName": "Holiday Camper Van 60283",
  "ProductLocalName": { "Value": "ホリデーキャンピングカー", "Language": "JA" }
}

ProductName is the brand’s short name of the product for the requested language. ProductNameInfo gives the international and the local name.

BrandPartCode, GTIN and GTINs

"BrandPartCode": "60283",
"GTIN": ["5702016889772"],
"GTINs": [ { "GTIN": "5702016889772", "IsApproved": true } ]

• BrandPartCode: the brand’s product code, the same as ProductCode in the request.
• GTIN: all confirmed GTINs of the product. A product can have more than one.
• GTINs: the same GTINs with their status. By default you receive only confirmed GTINs (IsApproved: true). To receive unconfirmed GTINs too, contact your account manager; they then appear in GTINs with IsApproved: false. GTIN always contains confirmed GTINs only.

Category and VirtualCategory

"Category": { "CategoryID": "151", "Name": { "Value": "Laptops", "Language": "EN" } },
"VirtualCategory": [
  { "VirtualCategoryID": "292", "UNCATID": "43211508", "Value": "Mobile Workstations", "Language": "EN" }
]

• Category: the bottom-level category of the product. You can match CategoryID with the category list in the Icecat reference files.
• VirtualCategory: some products also belong to one or more virtual categories, which describe the product more precisely, for example Chromebooks within Laptops. UNCATID is the UNSPSC code of the virtual category. VirtualCategory appears only when the product has one.

ProductFamily and ProductSeries

"ProductFamily": { "ProductFamilyID": "68786", "Value": "G5", "Language": "EN" },
"ProductSeries": { "SeriesID": "5958", "Value": "City Great Vehicles", "Language": "EN" }

Some brands group their products into families and series. In Apple iPod Touch, Apple is the brand, iPod the product family and Touch the series. Empty {}, or without Value, when the product has no family or series.

Description

"Description": {
  "ID": "62636579",
  "LongDesc": "<b>Power-packed. Adventure-ready.</b><br>15-inch gaming laptop …",
  "LongProductName": "15.6\" FHD (1920 x 1080) IPS, Intel Core i7-8750H …",
  "MiddleDesc": "",
  "Disclaimer": "",
  "ManualPDFURL": "https://…",
  "ManualPDFSize": "20779353",
  "LeafletPDFURL": "https://…",
  "PDFSize": "1422507",
  "URL": "https://www.dell.com/…",
  "WarrantyInfo": "12 Months Collect and Return",
  "Updated": "2018-07-16 14:25:35",
  "Language": "EN"
}

• ID: the ID of this description.
• LongDesc, MiddleDesc: marketing texts of different lengths. They are HTML: you may find the tags <b>, <br>, <p>, <sup>. Line breaks are already converted to <br>. They can contain footnote marks such as [1], explained in Disclaimer.
• LongProductName: a long name of the product.
• Disclaimer: legal notes and the explanation of footnotes.
• ManualPDFURL + ManualPDFSize, LeafletPDFURL + PDFSize: a link to the main user manual and to the main leaflet, with their size in bytes. The Multimedia section lists all documents of the product, with their type and language, and with your content token added. We recommend using Multimedia for documents.
• URL: the brand’s product page used as a source.
• WarrantyInfo: the official warranty and its conditions. When the brand gave none, a general warranty text in the requested language is shown.
• Updated: when the description was last changed, format YYYY-MM-DD HH:MM:SS.
• Language: the language of this description.
• TaxonomyName: present only when the description is exclusive content for a Channel Partner (see section 7).

SEOs

"SEOs": { "Title": "", "Description": "", "Keywords": "artificial flowers, sets for adults" }

• Title: the meta title of the product page, shown in search results and in the browser tab.
• Description: the meta description, often shown below the title in search results.
• Keywords: keywords for the product page.
• TaxonomyName: present only for partner-exclusive SEO texts (see section 7).

SummaryDescription

"SummaryDescription": {
  "ShortSummaryDescription": "LEGO City Holiday Camper Van, Building set, 5 yr(s), Plastic, 190 pc(s), 379 g",
  "LongSummaryDescription": "LEGO City Holiday Camper Van. Product type: Building set, Recommended age (min): 5 yr(s), …"
}

Short and long summaries, generated automatically by Icecat from the product’s main data and key specifications.

BulletPoints and GeneratedBulletPoints

"BulletPoints": {
"BulletPointsId": "3365318",
"Language": "EN",
"Values": ["…", "…"],
"Updated": "2024-02-28 11:33:30"
},
"GeneratedBulletPoints": {
"Language": "EN",
"Values": ["Gaming Laptop Clamshell Black", "Intel® Core™ i7 i7-8750H 2.2 GHz Processor cores: 6", "…"]
}

• BulletPoints: the key selling points the brand wants to stress. TaxonomyName appears when they are partner-exclusive (see section 7). Empty {} when the brand gave none.
• GeneratedBulletPoints: bullet points generated by Icecat from the specifications. Use them when BulletPoints is empty.

6.3 Image

The main image of the product: the first image a shopper sees.

{
  "HighPic": "https://…",  "HighPicSize": "361109", "HighPicHeight": "1280", "HighPicWidth": "1280",
  "LowPic": "https://…",   "LowPicSize": "20370",   "LowPicHeight": "200",   "LowPicWidth": "200",
  "Pic500x500": "https://…", "Pic500x500Size": "93169", "Pic500x500Height": "500", "Pic500x500Width": "500",
  "ThumbPic": "https://…", "ThumbPicSize": "4339"
}

Every image comes in four versions:

With each link you receive the size in bytes (…Size) and, except for the thumbnail, the height and width in pixels.

Image is the same image as the gallery image marked IsMain: "Y". When the product has no images, Image may show the brand logo, or be empty {}.

6.4 Gallery

All images of the product.

[
  {
    "ID": "25653364",
    "LowPic": "https://…", "LowSize": "20370", "LowHeight": "200", "LowWidth": "200",
    "ThumbPic": "https://…", "ThumbPicSize": "4339",
    "Pic": "https://…", "Size": "361109", "PicHeight": "1280", "PicWidth": "1280",
    "Pic500x500": "https://…", "Pic500x500Size": "93169", "Pic500x500Height": "500", "Pic500x500Width": "500",
    "No": "1",
    "IsMain": "Y",
    "Updated": "2024-03-14 17:44:45",
    "IsPrivate": "0",
    "Type": "ProductImage",
    "Attributes": { "OriginalFileName": "" }
  }
]

• ID: the ID of the image.
• Pic, Pic500x500, LowPic, ThumbPic: the four versions, as in Image.
• No: the position of the image. The lowest number comes first. Brands order their images in the most appealing way, so we recommend keeping this order.
• IsMain: Y for the main image, which is also shown in Image; N for the others.
• Updated: when the image was last changed, format YYYY-MM-DD HH:MM:SS. Download the image again when this date changes.
• IsPrivate: 1 for images the brand shares only with its authorised resellers. You receive them only when you are one (see section 8).
• Type: what the image shows, for example ProductImage, PackshotFront-Center, LifestyleImage, ProductPackagingImage, ProductDetailImage, Screenshot, BrandLogo. See How to Make the Product Gallery Great Again.
• Attributes → OriginalFileName: the brand’s original file name, when known.
• TaxonomyName: present when the gallery is partner-exclusive (see section 7).

When the product has no images, the gallery may contain only the brand logo.

6.5 Multimedia

All documents, videos, 360° tours, energy labels and product stories, in one list. The fields depend on the type.

Fields of every item

Types

Generated brochure. For Open Icecat brands that provide no leaflet, Icecat adds a generated brochure of the product: Type leaflet, Size 0, Description “Brochure” + brand + product code.

Videos

{
  "ID": "44449113-DA4C-46B9-8621-F6F344F7ED50",
  "URL": "https://…",
  "Type": "video/mp4",
  "ContentType": "video/mp4",
  "KeepAsUrl": "0",
  "Description": "Product video",
  "Size": "1201332",
  "IsPrivate": "0",
  "Updated": "2024-02-28 11:45:05",
  "Language": "",
  "IsVideo": 1,
  "ThumbUrl": "https://…",
  "PreviewUrl": "https://…"
}

• ContentType: video/mp4 for video files, text/html for external videos (KeepAsUrl: "1").
• ThumbUrl, PreviewUrl: a small and a large preview picture.

Documents

{
  "ID": "ECBC44BE-018E-44E6-B8F6-8D93E61416C8",
  "URL": "https://…",
  "Type": "manual pdf",
  "ContentType": "application/pdf",
  "KeepAsUrl": "0",
  "Description": "User manual",
  "Size": "20779353",
  "IsPrivate": "0",
  "Updated": "2018-05-16 11:02:30",
  "Language": "EN",
  "IsVideo": 0
}

For the user manual, the leaflet, the EU Product Fiche and the EU energy label, Description is a standard name in the requested language, for example “User manual” or “Product Brochure”.

Energy labels

Energy-label items have extra fields:

When there is no EU Product Fiche in the requested language, you receive the English one.

360° tours

{
  "ID": "9E013A07-3B14-4864-820E-7AFDB7A07600",
  "URL": "https://…",
  "Type": "360",
  "ContentType": "image/jpeg",
  "KeepAsUrl": "0",
  "Description": "360",
  "Size": "249254",
  "IsPrivate": "0",
  "Updated": "2020-11-24 13:52:25",
  "Language": "",
  "IsVideo": 0,
  "3DTour": [
    { "Link": "https://…", "Link400": "https://…", "Link1000": "https://…", "Link2000": "https://…", "OrderNumber": "0" }
  ],
  "PreviewURL": "https://…",
  "PreviewSize": "249254",
  "PreviewHeight": "1125",
  "PreviewWidth": "2000"
}

• 3DTour: the pictures of the product from every angle, clockwise, in the order of OrderNumber. Each picture comes in its original size (Link) and in three widths: Link400, Link1000 and Link2000.
• PreviewURL, PreviewSize, PreviewHeight, PreviewWidth: the front picture, used as preview.

Product stories

{
  "ID": "4FE39CDC-7773-48BD-BD74-2A6DF1BAF77B",
  "URL": "https://…/index.html",
  "Type": "ProductStory",
  "ContentType": "application/zip",
  "KeepAsUrl": "0",
  "Description": "ProductStory",
  "Size": "1793",
  "IsPrivate": "0",
  "Updated": "2024-12-20 10:28:31",
  "Language": "DE",
  "IsVideo": 0
}

A product story is a rich, brand-designed presentation of the product. Type is ProductStory or ProductStory2.0. To show product stories on your pages, see Manual: How to Embed Product Stories into Your Website?.

6.6 FeaturesGroups

The specifications of the product, in groups.

[
  {
    "ID": 10674,
    "SortNo": "1000",
    "FeatureGroup": { "ID": "148", "Name": { "Value": "Design", "Language": "EN" } },
    "Features": [ … ]
  }
]

• ID: the ID of the group within this category.
• SortNo: the position of the group. The highest SortNo comes first.
• FeatureGroup: the general ID of the group and its name in the requested language. It is not the same ID as ID.

Features

{
  "Localized": 0,
  "ID": 275632011,
  "LocalID": 0,
  "Type": "dropdown",
  "Value": "Notebook",
  "CategoryFeatureId": "101037",
  "CategoryFeatureGroupID": "10674",
  "SortNo": "100",
  "PresentationValue": "Laptop",
  "RawValue": "Notebook",
  "LocalValue": "Laptop",
  "Description": "The sub-category of the product.",
  "Mandatory": "1",
  "Searchable": "1",
  "Optional": "0",
  "Feature": {
    "ID": "14052",
    "Sign": "",
    "Measure": { "ID": "29", "Sign": "", "Signs": { "ID": "", "_": "", "Language": "EN" } },
    "Name": { "Value": "Product type", "Language": "EN" }
  }
}

• Value, RawValue: the raw value. Use it for search, filters and comparison.
• PresentationValue: the value formatted for display, in the requested language. Use it on your product page.
• LocalValue: the value translated into the requested language, when a translation exists.
• Localized: 1 when the value has a local version (LocalID), 0 when only the international value exists. ID is the ID of the international value, LocalID of the local one.
• Type: the type of specification, for example dropdown.
• CategoryFeatureId, CategoryFeatureGroupID: the specification and the group within this category. You can match them with the category feature list in the Icecat reference files.
• SortNo: the position of the specification in its group. The highest SortNo comes first.
• Description: an explanation of the specification, for example for a tooltip on its name.
• Mandatory, Searchable, Optional: technical settings of the specification in this category.
• Feature → ID: the general ID of the specification.
• Feature → Name: the name of the specification in the requested language. When it has no name in that language, you receive the English name.
• Feature → Measure → ID: the unit of measure. Measure → Signs → _ is the unit sign in the requested language, for example cm.
• Feature → Sign and Measure → Sign are always empty. Use Measure → Signs → _.

6.7 FeatureLogos

Logos linked to a specification, such as certificates, technologies or age warnings.

[
  {
    "LogoPic": "https://…",
    "Width": "300",
    "Height": "299",
    "Size": "0",
    "ThumbPic": "https://…",
    "FeatureID": "9733",
    "Value": "2.0",
    "KeyLogo": 0,
    "Description": { "Value": "<b>Higher Performance When You Need It Most</b> …", "Language": "EN" }
  }
]

• LogoPic: the logo in high resolution, with Width and Height in pixels.
• Size: always 0.
• ThumbPic: a thumbnail of the logo.
• FeatureID: the specification the logo belongs to.
• Value: the specification value for which the logo is shown.
• KeyLogo: a logo linked to several specifications appears once per specification, each time with the same KeyLogo.
• Description: an explanation of the logo in the requested language, for example for a tooltip.

6.8 ReasonsToBuy

The key advantages of the product, with a title, a text and often a picture.

{
  "ReasonToBuyID": "34208101",
  "Value": "Dell gaming machines are engineered with the specific, demanding needs of the gaming audience in mind. …",
  "HighPic": "https://…",
  "HighPicSize": "0",
  "No": "1",
  "Title": "Dell Gaming",
  "Language": "EN",
  "Updated": "2021-09-29 13:41:53",
  "Origin": "RTB",
  "IsPrivate": "0"
}

• Title, Value: the heading and the text. Line breaks in Value are converted to <br>.
• HighPic: a picture that goes with the text. HighPicSize is always 0.
• No: the position. The lowest number comes first.
• Origin: RTB for a reason to buy written by the brand, FeatureLogo for a feature logo used as a reason to buy, for example a certificate. Items are grouped by origin.
• IsPrivate: 1 for items the brand shares only with its authorised resellers.

6.9 Reviews

Reviews of the product from external review sites. You receive them when reviews are included for your account or for the product’s brand; otherwise the list is empty.

{
  "ID": 2050785,
  "Score": 76,
  "URL": "https://www.gadgetspeak.com/review/…",
  "IsActive": true,
  "Published": "2018-10-31",
  "Value": "Not a light machine and while it does have good battery life …",
  "ValueGood": "",
  "ValueBad": "",
  "BottomLine": "",
  "Language": "EN",
  "IcecatID": 56195846,
  "AwardHighPic": "", "AwardLogoPic": "", "Code": "", "DateAdded": "", "Group": "", "LogoPic": "", "Updated": ""
}

• ID: the ID of the review.
• Score: the score the review gives the product.
• URL: a link to the full review.
• IsActive: false when the link to the review no longer works.
• Published: when the review was published, format YYYY-MM-DD.
• Value, ValueGood, ValueBad, BottomLine: the review text, its pros, its cons and its conclusion. Long texts are shortened.
• Language: the language of the review.
• IcecatID: the Icecat product ID.
• AwardHighPic, AwardLogoPic, Code, DateAdded, Group, LogoPic, Updated are currently always empty.

6.10 ProductRelated

Products related to this one: accessories, consumables, services, alternatives and compatible products.

{
  "ID": 0,
  "CategoryID": 577,
  "Preferred": 0,
  "IcecatID": 31038491,
  "ProductCode": "960-001063",
  "ThumbPic": "",
  "ProductName": "C270 HD WEBCAM",
  "Brand": "Logitech",
  "BrandID": 91,
  "ProductRelatedLocales": [
    { "ID": 0, "Language": "EN", "Preferred": 0, "StartDate": "", "EndDate": "" }
  ],
  "RelationTypeCode": "accessory"
}

• IcecatID, ProductCode, Brand, BrandID: the identifiers of the related product. Request its data sheet with icecat_id.
• CategoryID: the category of the related product.
• ProductName: the short name of the related product.
• RelationTypeCode: what the related product is to this product:RelationTypeCodeMeaningaccessoryAn accessory for this productconsumableA consumable for this productserviceA service for this productalternativeAn alternative to this productcompatibleA product this one is compatible withunclassifiedA related product whose relation is not classified yetemptyA relation without a type
• ProductRelatedLocales → Preferred: 1 when the brand recommends this related product, 0 otherwise. StartDate and EndDate: when the relation starts and ends, when known.
• ID, Preferred (at the top level) and ThumbPic are kept for compatibility: ID may be 0, Preferred is always 0 and ThumbPic always empty.

How many related products you receive. At most 500 per relation type: up to 500 accessories, 500 consumables, 500 services and so on, not 500 in total. To receive fewer, set relationsLimit, for example relationsLimit=20 for up to 20 of each type. A value above 500 returns no more than 500. A value that is not a positive whole number is refused with error 30.

6.11 CatalogObjectCloud

A permanent public product page and a QR code that opens it. The page shows all available product information, independent of any shop. Some Channel Partners print the QR code on marketing materials, so that shoppers can see the full product information without being tied to a particular shop.

Available only for products of Open Icecat brands without publication restrictions; otherwise {}.

{
  "ProductPage": {
    "QRCodeURL": "https://qr.icecat.biz/coc/…",
    "URL": "https://coc.icecat.biz/…"
  }
}

• URL: the permanent product page.
• QRCodeURL: a QR code that opens that page.

6.12 Variants

Versions of the product that share its content but differ in one or two aspects, for example colour. Each variant lists only what is different from the main product.

[
  {
    "VariantID": "382",
    "VariantIdentifiers": [
      { "Identifier Type": "GTIN13", "Value": "1239967890129", "IsApproved": true },
      { "Identifier Type": "BrandProductCode", "Value": "12180C20T-3" }
    ],
    "VariantFeatures": [ { "VariantFeature SpecID": "<specification ID>", "Value": "<value>", "Language": "EN" } ],
    "VariantImages": [],
    "VariantMultimedia": [],
    "VariantDescriptions": "<b>Apollo 12.180 Watch strap Leather Beige</b> …"
  }
]

• VariantID: the ID of the variant.
• VariantIdentifiers: the product codes (BrandProductCode) and GTINs (GTIN13) of the variant. Note the space in the key Identifier Type. GTINs follow the same confirmed / unconfirmed rule as GTINs in GeneralInfo.
• VariantFeatures: the specifications that differ. VariantFeature SpecID is the general ID of the specification. Language is missing for international values, which apply to all languages.
• VariantImages, VariantMultimedia: currently always empty [].
• VariantDescriptions: the description of the variant.

6.13 ProductStory

The ProductStory-type items of Multimedia, repeated here, with the same fields. Items of type ProductStory2.0 appear only in Multimedia.

With an Open Icecat subscription, you can sometimes receive the product story of a Full Icecat product with content=productstory. See Product stories of Full Icecat brands for Open Icecat accounts.

6.14 Dictionary

Labels in the requested language that Icecat Live uses on its pages, for example “Specs” or “Product code”. You can safely ignore this section.

6.15 Granular-only and partial sections

These sections are returned only when you ask for them in content.

EssentialInfo

content=essentialinfo. Granular only. The identifiers and names of the product: Brand, ProductCode, ProductFamily, ProductSeries, ProductName, ProductNameInfo, GTIN, GTINs. The fields are as in GeneralInfo.

Title

content=title. Title and TitleInfo, as in GeneralInfo.

MarketingText

content=marketingtext. The long description (LongDesc from Description) as MarketingText, with its Language, and TaxonomyName when it is partner-exclusive.

Description, BulletPoints, GeneratedBulletPoints

content=description, content=bulletpoints, content=generatedbulletpoints. The same blocks as in GeneralInfo, on their own.

Manuals

content=manuals. Only the documents from Multimedia: user manuals, leaflets, EU and UK energy labels, EU Product Fiches, size charts, safety data sheets and other digital assets.

Videos

content=videos. Only the videos from Multimedia.

Tours3d

content=tours3d. Only the 360° tours from Multimedia.

Packages

content=packages. Granular only. The packaging of the product, as required under the EU’s Extended Producer Responsibility (EPR) rules. Each package is a product in a packaging category, with its own Icecat product ID, so you can request the data sheet of the package itself by icecat_id.

"Packages": [
  {
    "CategoryID": 9563,
    "IcecatID": 12345678,
    "ProductCode": "123456#MPN",
    "BrandID": 1,
    "ProductName": "Primary packaging name",
    "GTINs": [ { "GTIN": "123456789012", "IsApproved": true } ]
  }
]

Empty [] when the product has no packaging information.

BrandOrganizations

content=brandorganizations. Granular only. The organisations behind the brand.

"BrandOrganizations": {
  "BrandOwner": {
    "Organization": {
      "ID": "0f0ac11a-bfb8-4bf0-bcc3-974928831290",
      "Name": "Apple Inc.",
      "CountryCode": "US",
      "State": "California",
      "City": "Cupertino",
      "Street": "One Apple Park Way",
      "HouseNumber": "-",
      "ZIP": "CA 95014",
      "URLs": ["https://www.apple.com/contact/"],
      "Emails": []
    }
  },
  "Licensees": [],
  "Representatives": [ { "ID": "173601183229804564", "Organization": { … } } ]
}

• BrandOwner: the company that owns the brand. A brand has one owner.
• Licensees: companies that make products under the brand. A brand can have several.
• Representatives: legal entities responsible for sustainability-related matters for the brand.
• Organization: ID, official Name, CountryCode (ISO 3166-1 alpha-2), State (only where applicable, for example in the US), City, Street, HouseNumber, ZIP, URLs (always present) and Emails (optional).

The structure is the same as in the BrandOrganizations reference file, without its Updated field. How to use these details, for example for the contact information required under the EU General Product Safety Regulation (GPSR), is explained in Manual: Retrieving GPSR related Contact Details.

Analytics

content=analytics. Granular only.

"Analytics": { "Popularity": 5063 }

Popularity: a popularity indicator of the product, based on how often it is viewed through Icecat. It is global: it counts all languages together, so you receive the same value whatever language you request.

7. Partner-exclusive content (TaxonomyName)

Some brands create content exclusively for one Channel Partner or for a group of Channel Partners: a description, bullet points, SEO texts, a gallery or a product story. Such content belongs to a taxonomy.

When your account has access to one or more taxonomies, Icecat follows your priority list: for each part of the data sheet, the first source in your list that has content for the requested language wins. When none of them has content, you receive the general brand content.

The TaxonomyName field tells you which taxonomy the content comes from. It appears only for partner-exclusive content: on Description, SEOs, BulletPoints, MarketingText, on every Gallery image, and on product-story items in Multimedia. General brand content has no TaxonomyName.

To set up access to taxonomies or change your priority list, contact your account manager.

8. Which products you receive and which you do not

A refused product is refused in full. You never receive part of a data sheet because of a restriction. The only exception is described in Product stories of Full Icecat brands for Open Icecat accounts.

Private files are left out, not marked. Images, documents, videos and reasons to buy that the brand shares only with its authorised resellers are simply not in the response when you are not one. When you are, they are included with IsPrivate: "1". If you have a relationship with a brand, you can request authorisation through the Icecat website.

What you can access changes over time. A product can be released, a brand can change its restrictions, and your subscription can change. A product that is refused today can be available tomorrow, and the other way round.

Product stories of Full Icecat brands for Open Icecat accounts

A brand can choose to make its product stories available to all Icecat users. In that case you can receive the product story of a Full Icecat product even with an Open Icecat subscription.

This works only when you request the product story on its own:

https://live.icecat.biz/api?lang=EN&shopname=<YOUR_USERNAME>&icecat_id=<ICECAT_ID>&content=productstory

• The rest of the data sheet stays Full Icecat content. A request for the whole data sheet, or for productstory together with any other section, returns error 9.
• If the brand has not made its product stories available to all users, the request returns error 9 as well.
• The brand’s other restrictions still apply: release date, restricted products and selected resellers (errors 14 and 15).
• You receive items of type ProductStory. Items of type ProductStory2.0 are not included.

9. Errors

An error response has this shape, and the HTTP status equals Code:

{
  "StatusCode": 18,
  "Code": 404,
  "Error": "Not Found",
  "Message": "Not found user by API Token"
}

All error codes

The table lists every StatusCode you can receive from the requests described in this manual. The message is shown in English.

Responses without a StatusCode

Before processing a response, always check that msg is OK.

10. Integration flows

Flow A: the PIF tells you what to fetch, Product JSON delivers the content

The recommended flow for a webshop or PIM that stores product content itself.

1. Download your Personal Index File (PIF) and compare it with your previous version. It tells you which of your products are new, changed or no longer available.
2. For each new or changed product, request its data sheet in JSON, one request per language.
3. Download the images, documents and videos from the response and host them yourself. Download a file again when its Updated date changes.
4. Update your database. When a product disappears from the PIF, or a request returns an error from section 8, stop using its content.

Flow B: the XML Index Files tell you what to fetch

For a mirror of the whole Icecat catalogue, or to find products you do not sell yet.

1. Process the XML Index Files every day. They list all products, and the products changed in the last 24 hours.
2. Request the data sheet of each new or changed product in JSON, by its Icecat product ID.
3. Continue as in Flow A, steps 3 and 4.

Flow C: granular calls for lighter requests

Request only what you need, when you need it:

• A product list or search results: content=essentialinfo,image gives names, identifiers and the main image, without the full data sheet.
• A gallery update: content=gallery when you only refresh images.
• Specifications for filters: content=featuregroups.
• Packaging data for EPR reporting: content=packages.

Smaller responses arrive faster and are easier to process.

Related manuals

• Manual for Channel Partners: How to Choose Your Integration with the Icecat Catalogue
• Manual for Channel Partners: Personal Index File (PIF)
• Manual for Channel and Brand Partners: Personal Catalog File (PCF)
• Manual for Channel Partners: Icecat Product XML
• Manual for Channel Partners: XML Index Files
• Manual for Channel Partners: Icecat Live HTML
• Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth
• Icecat Locales and Language Code Table
• Manual for Reference Files XML
• Manual: Retrieving GPSR related Contact Details
• Manual: How to Embed Product Stories into Your Website?
• How to Make the Product Gallery Great Again