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

Placeholder	What it is	Where you get it
{productId}	your product in Icecat	the answer you got when you created the product
{gtinId}	one GTIN entry of one product	ean_id when you read the product’s GTINs, GtinId in a write answer

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

What you want to do	Call	Explained in
see the GTINs a product has	GET https://bo.icecat.biz/rest/ProductGTIN?filter={"product_id":{productId}}	§3
add or update GTINs, one or many	PUT https://bo.icecat.biz/restful/v3/ProductGtins	§4
confirm one GTIN for export	PATCH https://bo.icecat.biz/rest/productgtin/{gtinId}	§6
remove one GTIN	DELETE https://bo.icecat.biz/rest/productgtin/{gtinId}	§7

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

Length	8, 12, 13 or 14 digits
Content	digits only, and not all zeros
Check digit	the last digit has to be the correct GS1 check digit for the rest

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:

StatusCode	StatusMessage	What happened
201	Created.	the GTIN is now on your product and was not there before
200	Modified.	the entry already existed and something about it changed
304	Not modified.	it was already exactly like this; nothing was written
400	the reason	this entry was refused — the rest of the batch still applied

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.

Policy	What it does to GTINs already on the product	When you want it
CreateOrReplace (default)	nothing is deleted. Your entries are added or updated, and everything else stays	you are adding a GTIN, or correcting one, and the product’s other GTINs are none of this call’s business
ReplaceAll	every GTIN on the product that is not in your batch is deleted	your system owns the product’s full list of GTINs and Icecat should mirror it exactly
ReplaceOwn	every GTIN on the product that your own account added and is not in your batch is deleted. GTINs added by anyone else are left alone	you own part of the list and share the product with another source

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

Gtin	8, 12, 13 or 14 digits, digits only, not all zeros, correct check digit
Stored form	padded with leading zeros to 13 digits
Batch entries in one call	1 to 150, and the same number may not appear twice in one batch
GTINs per product	not limited
The same GTIN on two products	impossible — submitting it moves it
PolicyName	CreateOrReplace (default), ReplaceAll, ReplaceOwn
Locale	none. A GTIN is international
Products	those of the brands assigned to your account

---

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

Status	What it means
200	applied. In a batch, check each entry’s own status as well
304	everything you sent was already exactly like this
400	the request, or one entry in it, is wrong
403	the product is not one your account is assigned
500	our side failed — retry with a backoff

Messages you will meet

Message	What happened	What to do
GTIN is not valid.	wrong length, a non-digit, all zeros, or a wrong check digit	check the number against section 2 — all four conditions answer the same message
The same GTIN is already present in the batch.	the same number twice in one submission	de-duplicate the batch
Skipped by policy rule.	under ReplaceOwn, that GTIN is on your product but was added by someone else	use CreateOrReplace if you mean to take it over
Icecat GTIN supports 8-12-13-14 length	the length is not one of the four	count the digits before sending
Failed update. is_exported now is true.	an attempt to unconfirm	confirming is one-way — remove the GTIN instead
Failed update. Supports: is_exported - parameter only.	the confirm call carried another field	that call changes one thing only
Access denied.	the product belongs to a brand your account is not assigned	check the product
Product does not exist.	no such product	check the id