Manual for Brand Partners: Icecat Product GTINs

Version: 1.0
Updated on: October 5th, 2026

This manual is for brand partners publishing the GTINs of their own products. It describes what a brand account can do and the limits that apply.

Read Manual for Brand Partners: Icecat Push-API (API-IN) first. This page continues it, and assumes you have it behind you: what a product is, how you authenticate, and what a brand account may see. None of that is repeated here.

1. Before you start

How to identify yourself

The same header as everywhere else in the Brand API, on every request:

Api-Token: your_api_token

The IDs you will be substituting

The product has to be yours. Every call below works on products of the brands your account is assigned to. Another brand’s product answers 403.

Two API versions, and why

GTINs are older than the Brand API’s current version, and the operations did not all move at once. Writing in bulk is on v3; reading, confirming one GTIN and removing one are on v1. You can see it in the paths below.

It matters for one thing: the parameter style follows the version, so the same idea is is_exported in a v1 body and IsExport in a v3 one. The credential does not change — Api-Token works on both.

Every operation, in one table

Section 8 collects every limit, and section 9 lists the messages you are most likely to meet.

2. What a GTIN is

A GTIN is the barcode number that identifies your product in trade — an EAN, a UPC, or the longer case code. It is how a partner recognizes that the product in their catalog and the product in yours are the same thing, so it is the single most valuable identifier you can supply.

It is international. A GTIN carries no locale, and nothing needs translating: the same number is used in every market.

A product can carry several. Different packaging, different regions, a case code alongside the unit code — all of them can sit on one product.

A GTIN belongs to one product at a time. Section 5 explains what happens when you submit one that already exists elsewhere.

What counts as a valid GTIN

Short codes are stored as 13 digits. A GTIN-8 or a GTIN-12 is padded with leading zeros when it is stored, so 12345670 comes back as 0000012345670. Send the number as it is printed on the product — the padding is ours to do, and you will see the padded form when you read it back.

3. Reading what a product has

GET https://bo.icecat.biz/rest/ProductGTIN?filter={"product_id":{productId}}

header:

Api-Token: your_api_token

The filter value is a small JSON object and has to be URL-encoded.

Each entry carries:

• ean_id — the id of this GTIN entry. This is the {gtinId} the confirm and remove calls take;
• ean_code — the number itself, in its stored 13-digit form;
• is_exported — whether it is confirmed for export. Section 6;
• country — the country the number’s prefix belongs to, worked out from the barcode itself. It is informational: a prefix says where the number was issued, not where the product is sold;
• source_name — where the GTIN came from.

4. Adding and updating GTINs

One call adds and updates one GTIN or a hundred and fifty.

PUT https://bo.icecat.biz/restful/v3/ProductGtins

headers:

Api-Token: your_api_token
Content-Type: application/json

body:

{
  "ProductId": {productId},
  "PolicyName": "CreateOrReplace",
  "Batch": [
    { "Gtin": "4007817327166" },
    { "Gtin": "4007817327173", "IsExport": false }
  ]
}

ProductId and Batch are required. PolicyName is not — leave it out and you get CreateOrReplace, which is the safe one. Section 5 covers the other two.

Reading the answer

The answer repeats every entry you sent with a verdict of its own:

Alongside the verdict, each entry may carry:

• GtinId — the ID of the stored entry, which you need for the confirm and remove calls;
• EditorUserId — who the entry belongs to now;
• StolenFromProduct — present only when the GTIN was taken from another product. Section 5.

The batch is best-effort per entry. One refused entry does not fail the others, so check the entries rather than only the HTTP status: the call can answer 200 with a refusal inside it.

5. The three policies, and what they delete

The policy decides what happens to the GTINs already on your product that your batch does not mention. Choose it deliberately: two of the three delete.

ReplaceOwn has one refusal of its own: if your batch names a GTIN that is on this product but was added by somebody else, that entry answers 400 Skipped by policy rule. rather than taking it over.

A GTIN that belongs to another product is moved to yours

Under every policy, a GTIN you submit that currently sits on a different product is taken off that product and attached to yours. It is not copied and it is not refused — a GTIN belongs to one product at a time, and the last write wins.

The answer tells you when this happened: the entry comes back with StolenFromProduct naming the product it was taken from. Check for that field. It is the only signal that your submission changed a product other than the one you addressed.

It works in the other direction too: whoever submits it next can move a GTIN away from your product. If one disappears from your product, this is why.

6. IsExport — confirming a GTIN

IsExport says whether the GTIN is confirmed and may be shared with channel partners. An unconfirmed GTIN stays on the product and is not distributed.

A GTIN is confirmed by default. Leave IsExport out and the entry is created confirmed. Send "IsExport": false when you are recording a number you are not yet sure of.

To confirm one later:

PATCH https://bo.icecat.biz/rest/productgtin/{gtinId}

{ "is_exported": true }

That call accepts is_exported and nothing else.

Confirming is one-way. Once a GTIN is confirmed it cannot be unconfirmed — the call answers Failed update. is_exported now is true. If the number turns out to be wrong, remove it (section 7) rather than trying to hide it.

7. Removing a GTIN

DELETE https://bo.icecat.biz/rest/productgtin/{gtinId}

The entry is removed from the product. The answer confirms it:

{ "message": "Deleted", "id": {gtinId} }

There is no deactivation here and nothing to switch back on: a removed GTIN is gone from the product, and the number is free for another product to claim.

To remove several as part of a wider update, use ReplaceAll or ReplaceOwn in section 5 — they delete what the batch does not mention, in one call.

8. Limits

9. When something goes wrong

The Brand API’s error shape applies here — Code, Error, Message, DetailedCode — as described in Manual for Brand Partners: Icecat Push-API (API-IN).

Messages you will meet