Manual for Channel Partners: Matching Your Catalogue Against Icecat

Version: 1.0
Updated on: October 28th, 2026

Icecat identifies a product by its GTIN, or by the combination of brand and product code. Your own catalogue identifies it by whatever your suppliers put in their feeds. Matching is the step that joins the two, so that every article in your shop knows which Icecat data sheet belongs to it.

This manual explains how to do that matching yourself, on your side, using two files you can download: an index file and SuppliersList. It describes the same matching logic Icecat applies to a catalogue you upload to us, so that your result and ours agree.

• The files are described in Manual for Channel Partners: XML Index Files and Manual for Channel Partners: Icecat Reference Files.
• If you would rather not build this at all, Icecat can do the matching for you and return only your products: see Manual for Channel Partners: Personal Index File (PIF).

1. Should you match it yourself?

Matching on your side is worth building when:

• Your assortment changes constantly. You add products daily and want them matched the moment they arrive, without waiting for a file to be regenerated.
• You want to keep the rules in your hands. Your own brand spellings, your own exceptions, your own decision about what counts as a confident match.
• You already process the index files. You are downloading the catalogue anyway; the matching is then one extra pass over data you have.

Have Icecat match for you — with the Personal Index File — when your catalogue is stable, when you do not want to maintain brand-name rules, or when you want the matching and the coverage report to come from the same source as the content.

The two are not exclusive. A common arrangement is to match the straightforward part yourself and send what is left over to Icecat.

2. What you need

All three are in the repository of your subscription, level4 for Full Icecat and freexml for Open Icecat. Take the index file in the language you sell in; take on_market.index instead of files.index if you only care about products that are actually distributed.

From your own side you need three columns per article: brand, product code and GTIN. Any two of them are enough to start; all three give the best result.

3. The rule in one paragraph

Match on GTIN first. If there is no GTIN, or it leads nowhere, match on brand plus product code. If neither works, the article is unmatched — leave it unmatched rather than guessing. There is no matching on product names: two different products can carry almost the same name, and a name match that is wrong is worse than no match at all.

4. Step one — prepare your own values

For each of your articles, make a lookup version of the three values, and keep the original next to it. You will need the original to show your staff what went wrong, and to send back to your supplier.

• Remove whitespace at the start and the end, and any invisible characters your feed carries.
• Do not change anything else. A product code is not a word: its dashes, slashes, dots and capitals are part of the identifier.
• Expect a product code of up to 60 characters and a GTIN of up to 14 digits. Anything much longer is a mis-mapped column — a description that ended up in the brand field, for example — and is worth rejecting before it costs you a matching run.

5. Step two — build the lookup tables

Read the index file once and build three tables. All three fit in memory for most assortments; if yours does not, load them into a database and index the keys.

And one more from SuppliersList.xml:

Fill the brand table from the Name attribute of each <Supplier> and from every <Names><Name> entry inside it. Localised brand names are brand names: a Greek or Japanese feed may well carry the local spelling.

For the mapped-code table, take the brand from the Supplier_id attribute of <M_Prod_ID> — not from the product’s own brand. An alternative code may belong to a different brand than the product it leads to.

6. Step three — normalise the GTIN

GTINs arrive in different lengths: EAN-8, UPC-12, EAN-13, GTIN-14, and all of them with or without leading zeros. Bring both sides to the same form, with exactly these two operations:

1. Remove the leading zeros.
2. If what is left is shorter than 13 characters, pad it with zeros on the left to 13.

So 0008710103759058 and 8710103759058 both become 8710103759058, and 05901234123457 becomes 5901234123457. Apply this to the GTINs in the index file and to the GTINs in your own catalogue, then compare them as strings.

Two points to decide before you run it:

• IsApproved. A GTIN that is not approved has been claimed but not yet confirmed. Icecat publishes it because it is usually right. You may accept it as a match, or keep those matches in a separate bucket for review — but decide deliberately rather than by accident.
• One GTIN leads to exactly one product. In the Icecat catalogue a GTIN identifies a single product, so your GTIN table holds one product per key, and a match on it is as strong as a match gets. The opposite is not true: one product can carry many GTINs, because packaging variants and regional versions share a data sheet. If your lookup ever ends up with two products under the same GTIN, do not pick one — that is a data problem on one side or the other. Leave the article unmatched and report both product IDs to your account manager.

7. Step four — resolve the brand

A brand reaches you as a name and must become a brand ID before the product code is of any use. Look the name up in your brand table, after trimming it and ignoring the difference between capitals and lower case.

That will not catch everything, and it is worth knowing why. When Icecat matches a catalogue internally, it tries the exact brand name first, and then a set of alias rules — alternative spellings and patterns such as HP* — that have been collected over years of processing supplier feeds. Those alias rules are not part of the exported files. What you get from SuppliersList is the official name and its localised forms.

So build your own small alias list and keep it next to your import. In practice it needs:

• the legal suffixes your suppliers add and Icecat does not: Inc., GmbH, B.V., Ltd;
• the punctuation differences: Hewlett-Packard against Hewlett Packard;
• the house spellings your own buyers use.

Every entry you add is one you will not have to add again. When a brand simply is not in SuppliersList, it is not in the Icecat catalogue — note it and move on; no spelling rule will fix it.

8. Step five — match the product code

With a brand ID in hand, look up brand ID plus product code in your code table. The comparison is exact: trimmed, but otherwise character for character. Do not strip dashes or spaces, and do not try to be clever — HR2345/19 and HR234519 are different codes, and only one of them is in the catalogue.

If that finds nothing, look the same pair up in your mapped-code table. This is where the alternative codes of section 5 earn their place: the code your supplier sent may be a regional code, a configuration code, or the code the product carried under a previous brand, and the mapping leads from it to the right product.

If both tables come up empty, the article is unmatched.

9. Step six — record the result

For every article, store at least:

Limited="Yes" means the brand releases that data sheet to assigned resellers only. The match is correct, but you need authorisation from the brand before you can show the content — request it on your MyIcecat page.

10. What to do with what did not match

Unmatched articles fall into a small number of groups, and each has its own answer:

Upload the remainder to Icecat as a catalogue file and let our matching run over it — it has the alias and mapping rules your side does not — and take the result back as your Personal Index File.

11. Keeping the match fresh

A match is not done once. The catalogue moves underneath it:

1. Every day, read daily.index and re-run the match for the lines you have not matched yet. Products gain GTINs and alternative codes over time; an article that failed yesterday can match today without anything changing on your side.
2. Act on Quality="REMOVED". The product is gone from the catalogue and your link to it will stop working. It appears in daily.index for one day only.
3. Watch Updated on the lines you did match, and re-fetch only those data sheets.
4. Re-run the whole match monthly against the full index file. New brands appear, mappings are added, and your own alias list has grown in the meantime.

12. A worked example

Your feed line:

Brand: PHILIPS      Code: HR2345/19/00     GTIN: 08710103759058

1. Trim the values. The brand becomes PHILIPS, the code stays HR2345/19/00, the GTIN stays 08710103759058.
2. Normalise the GTIN: strip the leading zero → 8710103759058, which is 13 characters, so no padding is needed.
3. Look it up in the GTIN table. Suppose it is not there — the brand has not registered this packaging variant with us.
4. Resolve the brand: PHILIPS matches Philips in SuppliersList ignoring case → brand ID 25.
5. Look up 25 + HR2345/19/00 in the code table. Not there: the brand’s main code is HR2345/19.
6. Look up 25 + HR2345/19/00 in the mapped-code table. Found → Product_ID 36153639.
7. Store the result: product ID 36153639, matched by product code, via a mapped code.

Had step 3 succeeded, steps 4 to 6 would never have run. That is the whole point of the order.

13. Reference: the keys at a glance