Manual for Channel Partners: Icecat Reference Files

Version: 2.1
Updated on: November 10th, 2026

Reference files are the dictionaries of the Icecat catalogue. A product data sheet refers to a brand, a category, a feature, a unit of measure or a language by its Icecat ID. Reference files tell you what those IDs mean. Download them once, refresh them on a schedule, and every ID you receive anywhere in Icecat (in a product XML or JSON, in an index file) becomes readable.

• To receive the list of products and their identifiers, see Manual for Channel Partners: XML Index Files.
• To compare the ways of receiving Icecat content, see Manual for Channel Partners: How to Choose Your Integration with the Icecat Catalogue.

1. Where the files are

Every reference file is published in two repositories, and you use the one your subscription gives you access to:

The file name is the same in both, for example https://data.icecat.biz/export/level4/refs/SuppliersList.xml.gz.

Every download is authenticated, in both repositories: a request without credentials is answered with 401. Reference files are gated exactly like product data sheets, and you have three ways in:

The access token is the one we recommend, for one practical reason: with a token, the IP whitelist on your account is not checked. With an application key or with basic authentication it is, so a download from a new server fails until that server’s address is added. See Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth.

Whichever you use, the account must be a Channel Partner account, and the repository must be the one your subscription covers.

1.1 Everything in one file

The reference lists are also published as one combined file, with the exception of CategoryFeatureIntervalsList, RelationsList and BrandOrganizations:

Note that the combined file sits one level higher than the individual lists — directly in the repository, not in the refs/ folder. It holds the same content; take it when you prefer one download over eleven, and take the individual files when you only need a few of them.

1.2 Advice on downloading

• Almost every file is gzipped. Send Accept-Encoding: gzip with your request.
• CategoryFeaturesList.xml is very large: about 1.6 GB as you download it, and over 10 GB once unpacked. It cannot be opened in a browser or in a normal text editor — read it with a streaming XML parser, and do not try to hold it in memory.
• A download that size will be interrupted sooner or later, and it cannot be continued from where it stopped. A request for a byte range brings the whole file back from the beginning — so curl -C - gives up, and wget -c and Invoke-WebRequest -Resume quietly start over. The answer to a HEAD request says accept-ranges: bytes, and that is the one part of it not to believe. The size in that answer is reliable: on a .gz address it is the number of bytes you will receive, so compare your finished file against it to see whether the download ran to the end. Plan for the restart instead: generous timeouts, one machine doing the download rather than several, and a schedule that does not depend on any single attempt succeeding. Manual for Channel Partners: Downloading Export Files, under “If the download is interrupted”, has the rest.
• Download reference files before the product data that refers to them, so that no ID in your import is unknown.

2. The inventory

The refs/ folder holds fourteen files:

Mind the extensions: CategoryFeatureIntervalsList and RelationsList are published uncompressed — ask for .xml, not for .xml.gz.

2.1 Which of them you actually need

Few partners need all fourteen. Start from what you are building:

SuppliersList and CategoriesList are the two that are never optional. Every product you receive carries a brand ID and a category ID, and nothing else in the catalogue decodes them.

The five feature files are not needed to display specifications. A product data sheet already arrives with the name of each feature, its value and its unit, in the language you requested. Those files matter when you want the structure rather than the text: the order features are shown in, the groups they belong to, which of them are worth offering as a filter, the allowed values behind a dropdown — or when you store specifications by ID and translate them yourself.

2.2 How the files join

Every reference file is a dictionary for an ID that reaches you somewhere else. This is the map of which ID leads where:

Read it as: a product gives you two numbers, Supplier_id and Catid. Everything else in the reference set hangs off those two, and langid decides which translation of any of it you read.

In each file section below you will find the same statement in words, under External connections, so you can follow it without the picture.

Each section also opens with a sample of the file. The samples are trimmed to show the shape — one entry instead of millions, one language instead of all of them, and values chosen to be readable. The tables next to them are the complete list of what you will meet.

3. Attributes you will meet everywhere

Translations are not carried the same way everywhere, and this will catch your parser. In CategoriesList, FeatureGroupsList, LanguageList and SupplierProductFamilies the translated text sits in a Value attribute: <Name ID="…" Value="Notebooks" langid="1"/>. In FeaturesList, MeasuresList, FeatureValuesVocabularyList and FeatureLogosList the same kind of text is the content of the element: <Name ID="…" langid="1">Processor frequency</Name>. Read both forms, and do not assume one file’s shape holds in the next.

Picture attributes repeat in the same sizes across the files that contain images:

4. The files you need to identify a product

These two files are what turns an index file, a data sheet or a feed into something you can join to your own catalogue. If you read only part of this manual, read this part.

4.1 SuppliersList — brands

Every product in Icecat belongs to exactly one brand, and that brand reaches you as a numeric Supplier_id. SuppliersList.xml is the only place where that number has a name.

<SuppliersList>
  <Supplier ID="1" Name="HP" Sponsor="1" Updated="20261012093000"
            LogoPic="..."><!-- logo attributes in five sizes, see the table -->
    <Names>
      <Name langid="1" Name="HP" Updated="20261012093000"/>
    </Names>
  </Supplier>
</SuppliersList>

External connections. Supplier ID is the Supplier_id of every product, the brand of a mapped product code, the brand in SupplierProductFamilies and the brand in BrandOrganizations.

Two things follow from this that matter in practice:

• A brand has more than one name. Next to the main Name, a brand can carry localised names. When you match your own assortment on brand name, build your lookup from the main name and every localised name, not from the main name alone.
• Sponsor tells you which subscription a product needs. Products of sponsoring brands are in Open Icecat; everything else requires Full Icecat.

4.2 CategoriesList — the category tree

Categories are a hierarchy. Products are only ever assigned to a bottom-level category; the top-level ones are called verticals and are used to split the catalogue into manageable parts (see the vertical index files in the index-files manual).

<CategoriesList>
  <Category ID="2" LowPic="..." Score="1234" Searchable="1" ThumbPic="..."
            UNCATID="43160000" Visible="1" Updated="20261012093000">
    <Versions>
      <UNSPSC code="43211503" version="26.0801" date_added="..." Updated="..."/>
    </Versions>
    <Description ID="884" Value="..." langid="1" Updated="..."/>
    <Keywords ID="12" Value="..." langid="1" Updated="..."/>
    <Name ID="2537" Value="Notebooks" langid="1" Updated="..."/>
    <ParentCategory ID="151">
      <Names>
        <Name ID="2536" Value="Computers" langid="1" Updated="..."/>
      </Names>
    </ParentCategory>
    <VirtualCategories>
      <VirtualCategory ID="88" UNCATID="43211508">
        <Name ID="9901" Value="Gaming notebooks" langid="1"/>
      </VirtualCategory>
    </VirtualCategories>
  </Category>
</CategoriesList>

External connections. Category ID is the Catid of every product, the category of a CategoryFeaturesList block, the Category_ID of a product family, and the category a licensee or representative is scoped to in BrandOrganizations.

The 24 verticals are: Telecom & Navigation; Office; AV & Photo; Food, Beverages & Tobacco; Health, Beauty & Personal Care; Domestic Appliances; Fashion & Lifestyle; Sports & Recreation; Vehicles; Baby & Children; Pet Care; Toys; Lighting; Home; Computers & Peripherals; Industrial & Lab Equipment; Entertainment & Hobby; Online Data Services; Building & Construction; Drugs & Pharmaceutics; Hospitality; Medical Equipment; Defense, Police & Safety; Packaging.

A full path looks like: Computers & Peripherals → Printers & Scanners → Printing Equipment → 3D Printers. Only the last level holds products.

CategoriesList does not tell you which specifications a category has. That is CategoryFeaturesList.

5. The files you need to read specifications

5.1 FeaturesList — what a feature is

<FeaturesList>
  <Feature Class="0" DefaultDisplayUnit="0" ID="5" Type="numerical"
           Updated="20261012093000">
    <Names>
      <Name ID="4410" langid="1" Updated="...">Processor frequency</Name>
    </Names>
    <Descriptions>
      <Description ID="884" langid="1" Updated="...">...</Description>
    </Descriptions>
    <Measure ID="16" Sign="MHz" Updated="...">
      <Signs>
        <Sign ID="31" langid="1" Updated="...">MHz</Sign>
      </Signs>
    </Measure>
    <RestrictedValues ValueSorting="0">
      <RestrictedValue/>
    </RestrictedValues>
  </Feature>
</FeaturesList>

External connections. Feature ID is referenced by CategoryFeaturesList and by FeatureLogosList; Measure points into MeasuresList; the restricted values of a dropdown are translated in FeatureValuesVocabularyList.

A feature can have no restricted values here and still have them within a category. Always check CategoryFeaturesList as well before you decide that a feature is free text.

5.2 CategoryFeaturesList — which feature belongs to which category

The largest reference file, and the one that makes a specification block renderable: it gives the features of each category, their order, their grouping and their category-specific restrictions.

<CategoryFeaturesList Code="1">
  <Category ID="2" LowPic="..." UNCATID="43160000" Updated="...">
    <CategoryFeatureGroup ID="120" No="10">
      <FeatureGroup ID="7">
        <Name ID="2537" Value="Processor" langid="1" Updated="..."/>
      </FeatureGroup>
    </CategoryFeatureGroup>
    <Feature CategoryFeatureGroup_ID="120" CategoryFeature_ID="111" IsHidden="0"
             Class="0" ID="5" LimitDirection="0" Mandatory="1" No="10100090"
             Searchable="1" Type="numerical" Use_Dropdown_Input="N"
             ValueSorting="0" Updated="...">
      <Measure ID="16" Sign="MHz" Updated="...">
        <Signs>
          <Sign ID="31" langid="1" Updated="...">MHz</Sign>
        </Signs>
      </Measure>
      <Name ID="4410" Value="Processor frequency" langid="1" Updated="..."/>
      <RestrictedValue/>
    </Feature>
    <Name ID="2537" Value="Notebooks" langid="1" Updated="..."/>
  </Category>
</CategoryFeaturesList>

External connections. Category ID comes from CategoriesList, Feature ID from FeaturesList, FeatureGroup ID from FeatureGroupsList, Measure ID from MeasuresList; and CategoryFeature_ID is what CategoryFeatureIntervalsList is keyed on.

5.3 FeatureGroupsList, FeatureValuesVocabularyList, MeasuresList

• FeatureGroupsList — the headings a specification table is divided into, for example “Power”. <Name Value> holds the translation. sid is deprecated.
• FeatureValuesVocabularyList — the translations of dropdown and multi-dropdown values. Key_Value is the English key, <FeatureValue> the translation. Group_ID is deprecated.
• MeasuresList — units for numerical features. <Sign> is the symbol and is HTML-encoded, so the symbol for inch arrives as ". <Name> and <Description> are per language.

<FeatureGroupsList>
  <FeatureGroup ID="7" sid="2537" Updated="20261012093000">
    <Name ID="2537" Value="Processor" langid="1" Updated="..."/>
  </FeatureGroup>
</FeatureGroupsList>

<FeatureValuesVocabularyList>
  <FeatureValuesVocabulary Group_ID="0" Key_Value="(2-in-1) Carpet cleaner &amp; deodorizer"
                           Updated="...">
    <FeatureValue ID="77012" langid="4" Updated="...">(2-in-1) Teppichreiniger &amp; Deodorierer</FeatureValue>
  </FeatureValuesVocabulary>
</FeatureValuesVocabularyList>

<MeasuresList>
  <Measure ID="16" Updated="20261012093000">
    <Descriptions>
      <Description ID="884" langid="1" Updated="...">...</Description>
    </Descriptions>
    <Names>
      <Name ID="3301" langid="1" Updated="...">megahertz</Name>
    </Names>
    <Sign>MHz</Sign>
    <Signs>
      <Sign ID="31" langid="1" Updated="...">MHz</Sign>
    </Signs>
  </Measure>
</MeasuresList>

External connections. Feature groups are referenced by CategoryFeaturesList; measures by both FeaturesList and CategoryFeaturesList; the vocabulary is keyed on the English restricted value that FeaturesList and CategoryFeaturesList carry.

5.4 CategoryFeatureIntervalsList — plausible ranges

For numerical category features, the range within which real values fall. Use it to catch import errors: a screen size of 4,000 inches is a unit mistake, not a product.

<CategoryFeatureIntervals category_feature_id="5" valid="4624" invalid="748"
                          ratio="0.861" updated="20261012093000">
  <Interval amount="43" order="1">
    <Min>0</Min>
    <Max>100</Max>
  </Interval>
</CategoryFeatureIntervals>

category_feature_id maps to CategoryFeature_ID in CategoryFeaturesList. valid and invalid count the values that fall inside and outside the ranges, and ratio is simply the first divided by their sum — 0 when there is nothing to judge. <Interval> carries amount, the number of values in that range, and order, which numbers the intervals from 1 upwards, sorted by their lower boundary; <Min> and <Max> are the boundaries themselves.

External connections. Keyed on CategoryFeature_ID from CategoryFeaturesList, and on nothing else.

5.5 FeatureLogosList — certificates and patents

Logos are generated from feature values rather than stored as fixed images, which is why they live in a reference file instead of in a gallery.

<FeatureLogo Feature_ID="2183" Height="100" ID="54" LogoPic="..." Size="4096"
             Width="100" SupplierId="1">
  <FeatureLogoCategories>
    <FeatureLogoCategory catid="2"/>
  </FeatureLogoCategories>
  <Descriptions>
    <Description ID="771" langid="1">...</Description>
  </Descriptions>
  <FeatureLogoFeatures>
    <FeatureLogoFeature ID="91" Feature_ID="2183">
      <FeatureLogoValues>
        <FeatureLogoValue ID="140">Yes</FeatureLogoValue>
      </FeatureLogoValues>
    </FeatureLogoFeature>
  </FeatureLogoFeatures>
</FeatureLogo>

Note one quirk of this file: the sample above sits inside a root element named <FeaturesList>, not <FeatureLogosList> as the file name suggests. Match on the <FeatureLogo> entries, not on the root.

External connections. Feature_ID comes from FeaturesList, catid from CategoriesList, SupplierId from SuppliersList.

<FeatureLogo> gives Feature_ID, SupplierId, LogoPic and the image dimensions; <FeatureLogoCategories> the categories it applies to; <FeatureLogoFeatures> the features that use it; <Descriptions> a short explanation per language. Note that the values which trigger the logo are nested inside each <FeatureLogoFeature>, not listed once for the whole logo: one logo can be triggered by different values of different features.

6. The files that describe the catalogue around a product

6.1 LanguageList

Languages and the countries they are used in. <Language Code ShortCode> — the full name and the code from the locales table; <Country Code System_Of_Measurement> — metric or imperial, which is what decides whether a specification is shown in centimetres or in inches. Sid is deprecated.

<LanguageList>
  <Language Code="english" ID="1" ShortCode="EN" Sid="2537" Updated="20261012093000">
    <Countries>
      <Country Code="GB" ID="77" System_Of_Measurement="metric" Updated="..."/>
      <Country Code="US" ID="78" System_Of_Measurement="imperial" Updated="..."/>
    </Countries>
    <Name ID="9012" Value="Englisch" langid="4" Updated="..."/>
  </Language>
</LanguageList>

External connections. Language ID is the langid on every translation in every other reference file, and the language of a product data sheet.

6.2 SupplierProductFamiliesListRequest

Product families and series of a brand, for example Acer TravelMate and, within it, TimelineX.

<SupplierProductFamiliesList>
  <ProductFamily Category_ID="151" ID="2" Updated="20261012093000">
    <Description ID="884" Value="..." langid="1" Updated="..."/>
    <Name ID="5501" langid="1" Value="TravelMate" Updated="..."/>
    <ParentProductFamily ID="1"/>
    <Series ID="34">
      <Name ID="5502" langid="1" Value="TimelineX" Updated="..."/>
    </Series>
    <Supplier ID="7" Name="Acer"/>
  </ProductFamily>
</SupplierProductFamiliesList>

<ProductFamily ID Category_ID Updated> with <Name> (English), <Description> per language, <ParentProductFamily ID> (an ID of 1 means the family is top level), <Series><Name> and <Supplier ID Name>.

External connections. Category_ID comes from CategoriesList, Supplier ID from SuppliersList, and the family itself is referenced by RelationsList as SupplierFamily.

6.3 DistributorList

The distributors that synchronise their catalogue with Icecat. It is what stands behind the On_Market flag and the country markets of a product: a product is on a market because a distributor confirms distribution there.

<DistributorList>
  <Distributor ID="2" Code="IM" Name="Ingram Micro - Netherlands (Iceimport)"
               Updated="20261012093000"/>
</DistributorList>

<Distributor ID Code Name Updated>. The file has no references to other reference files.

External connections. None in the files. Its effect is visible elsewhere: a distributor is why a product carries On_Market="1" and a list of country markets in the index files.

6.4 RelationsList

Cross-sell and up-sell rules, expressed as groups of rules rather than as product pairs.

<RelationGroup ID="82" name="Dynabook" description="...">
  <Relation ID="5" name="Docking stations for notebooks">
    <SourceIncludeRules>
      <Rule ID="610">
        <Supplier ID="7" />
        <Category ID="2" />
        <Feature ID="5" exact="more"><![CDATA[2400]]></Feature>
      </Rule>
    </SourceIncludeRules>
    <SourceExcludeRules>
      <Rule ID="611">
        <SupplierFamily ID="44" />
      </Rule>
    </SourceExcludeRules>
    <DestinationIncludeRules>
      <Rule ID="612">
        <Supplier ID="7" />
        <Category ID="573" />
        <Prod_id value="PA5356U-1PRP" />
        <Start_date value="2026-01-15" />
        <End_date value="2026-12-31" />
      </Rule>
    </DestinationIncludeRules>
  </Relation>
</RelationGroup>

<RelationGroup> holds <Relation>s, and a relation has up to four rule sets: <SourceIncludeRules> and <SourceExcludeRules> describe what the customer is looking at, <DestinationIncludeRules> and <DestinationExcludeRules> what to recommend. The exclude sets are subtractions — apply them, or you will recommend what the rule was written to keep out. A set is written only when it has rules, so expect any of the four to be missing.

Inside a <Rule ID>, every condition is an element with an attribute, never text:

A rule carries only the elements it needs, so two rules in the same set can look nothing alike.

External connections. Supplier comes from SuppliersList, Category from CategoriesList, SupplierFamily from SupplierProductFamilies, and Prod_id is the product code you see in the index files.

6.5 BrandOrganizations

Who owns, licenses and represents a brand, and where to reach them. This is the file behind your GPSR contact details, and the roles in it map onto the roles the regulation asks for. Which organisation you have to show for a given product, and how the category scopes decide that, is set out in Manual: Retrieving GPSR related Contact Details — read it before you build on this file. That manual also covers the CSV form of the same data, and the ways to receive brand organisations inside a product data sheet rather than as a reference file.

<BrandOrganizations>
  <Brand ID="1" Updated="2026-10-12 09:30:00">
    <BrandOwner>
      <Organization ID="3f2a…" Name="HP Inc." CountryCode="US" State="CA" City="Palo Alto"
                    Street="Hanover Street" HouseNumber="1501" ZIP="94304">
        <URLs>
          <URL>https://www.hp.com</URL>
        </URLs>
        <Emails>
          <Email>compliance@example.com</Email>
        </Emails>
      </Organization>
      <Scopes>
        <Categories>
          <Category ID="2"/>
        </Categories>
      </Scopes>
    </BrandOwner>
    <Licensees/>
    <Representatives>
      <Representative ID="77">
        <Organization ID="8b14…" Name="HP Europe B.V." CountryCode="NL" City="Amstelveen">
          <URLs/>
          <Emails/>
        </Organization>
        <Scopes>
          <Categories>
            <Category ID="2"/>
          </Categories>
        </Scopes>
      </Representative>
    </Representatives>
  </Brand>
</BrandOrganizations>

External connections. Brand ID comes from SuppliersList, and the categories inside <Scopes> from CategoriesList.

<Brand ID Updated> — the brand ID from SuppliersList; note that Updated here is written as YYYY-MM-DD HH:MM:SS, not as the compact timestamp used elsewhere. Inside it, <BrandOwner>, <Licensees> and <Representatives> carry <Organization> records with ID (a UUID), Name, CountryCode, State, City, Street, HouseNumber and ZIP, each followed by <URLs> and <Emails> whose entries are the text of <URL> and <Email> elements, not attributes. Licensees and representatives have an ID of their own on top of the organisation’s.

All three roles carry <Scopes>, the brand owner included — the categories that role covers. An empty <Scopes> means the role is not limited to any category. The three containers are always written, so <Licensees/> standing empty means this brand has none, not that the data is missing.

7. How often to refresh

Use the Updated attribute rather than the file timestamp to decide what to re-import.

8. Troubleshooting