Manual for Channel Partners: Personal Index File (PIF)

Version 1.0
Updated on: October 30th, 2026

This manual explains how to build the Personal Index File into an automated integration: when we recommend it, how to keep it up to date automatically, how to download it with an API token, and which integration flows to build on top of it. Use it if you have your own product catalogue and want to know which of your products Icecat covers, and when their content changes.

To generate and download the PIF by hand, see Manual for Channel and Brand Partners: Downloading Your Personal Files in MyIcecat.

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

1. What the PIF is

The Personal Index File is a CSV list of your products that Icecat matched against its catalogue. For each matched product it gives you:

• the Icecat identifiers: brand, product code and GTINs;
• a link to the full product data sheet (XML) in every language of your subscription;
• the date the product content was last changed in the Icecat catalogue;
• your own identifiers, repeated next to ours, so you can join the file to your own database;
• a message when you are not allowed to access the product.

The PIF does not contain product content itself, such as descriptions, specifications or images. It is the index that tells you what to fetch and when to fetch it again.

2. When we recommend the PIF

We recommend the PIF when you have a defined catalogue of products and:

• You do not want to match your products yourself. You could match your assortment against our global XML index files, but then you would have to work through the whole Icecat catalogue to find your own products. With the PIF, Icecat matches for you and gives you only the products you sell.
• You want to check for updates on your own schedule. Our daily index lists the products that changed in the last 24 hours. If you skip a day, you miss those changes. The PIF instead gives every product the date it was last changed in our catalogue. You can check weekly or monthly and still miss nothing. In effect, you build your own “daily index” from the PIF.

3. Before you start

1. Upload your product file and match it. See the Matching and Coverage Analysis of Your Catalog. Only matched products appear in the PIF.
2. Map your identifiers. When you upload the file, indicate which columns hold your own product ID, product code (MPN), brand name and GTIN. The PIF only returns the identifiers you mapped (see section 4).
3. Generate your first PIF by hand on the My downloads page in MyIcecat (see Downloading Your Personal Files in MyIcecat). Check that it contains the products and columns you expect. Until a PIF exists, the download address in section 7 returns status 204 with an empty body.
4. Get an API token. See Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth. Treat the token like a password: keep it on your server only, never in a web page.

If you want your PIF to update automatically

Without regular updates, your PIF is rebuilt only when you generate it on the My downloads page. With regular updates, Icecat re-matches your product file and rebuilds your PIF automatically. To get there:

1. Give us a link to your product file, not a file from your computer. Choose the URL option when you upload. Icecat then downloads your file again and re-matches it automatically. A file uploaded from your computer is a one-time snapshot: it is never re-matched automatically, and the regular-updates request in the next step is not offered for it. If you need a place to host the file, see How to host your Product Feed.
2. Request regular updates. On the My downloads page, click Request updates (see Downloading Your Personal Files in MyIcecat, section 7). Your request goes to Icecat, and we switch regular updates on for your account. You can send one request every 7 days.
3. If regular updates are not switched on after your request, contact your account manager.

4. Columns

The columns appear in this order. Columns marked conditional appear only in the situation described.

Why columns 8–10 matter. Icecat matches products even when your code or brand is spelled differently from ours. prod_id and supplier_name show the Icecat spelling, and columns 8–10 show yours, so you can link every PIF row back to the right row in your own file.

File format. CSV, comma-separated, values in double quotes, UTF-8. The first line is the header. There is one row per matched line of your product file, in the same order. If your file lists the same product twice, the PIF does too.

5. The data sheet link, and how to get JSON instead

Each path(<language>) link points to the XML data sheet of the product. The number just before .xml is the Icecat product ID:

https://data.icecat.biz/export/level4/EN/12345678.xml
                                         ^^^^^^^^
                                         Icecat product ID

If you prefer JSON. The PIF does not offer JSON links yet. Until it does, you can take the Icecat product ID from the link and request the same product in JSON:

https://live.icecat.biz/api?lang=en&shopname=<YOUR_USERNAME>&icecat_id=12345678&content=

Authenticate as described in the Manual for Channel Partners: Icecat Product JSON. JSON does not support the INT language.

This is a temporary workaround. Use the link from the PIF as the source of the product ID, and do not build XML links yourself.

6. Which products are in the PIF and which are not

The PIF changes from one version to the next, even when your product file does not. The Icecat catalogue is dynamic:

• New rows appear when a product gets a data sheet or becomes matchable because you add a brand or a GTIN.
• Rows disappear when you remove a product from your file, or when you lose access to it.
• error_message can change in either direction, for example when a product’s release date passes.

So on every run, compare the whole file with your previous version, not only the timestamp column (see section 8).

7. Downloading the PIF

Request

GET https://bo.icecat.biz/restful/v3/PersonalIndexFile
Api-Token: <API_TOKEN>

• Your API token goes in the Api-Token request header, not in the address. Replace <API_TOKEN> with your token. The token must belong to a Channel Partner account.
• The response is a CSV file named PIF.csv.

curl -o PIF.csv -H "Api-Token: <API_TOKEN>" "https://bo.icecat.biz/restful/v3/PersonalIndexFile"

Check that your file is ready

GET https://bo.icecat.biz/restful/v3/PersonalIndexFile/Status
Api-Token: <API_TOKEN>

The response reports Status and OutputFileSize. Download only when Status is Done, and compare the number of bytes you received with OutputFileSize. A shorter file means the transfer was cut — repeat it.

An empty response

While your PIF is being rebuilt, and before your first PIF exists, the address returns status 204 with an empty body. This is not an error.

Never replace your previous PIF with an empty response. Keep your previous version and try again later.

Errors

8. Integration flows

Flow A: the PIF as your own daily index, with XML or JSON for the content

The PIF tells you what changed, and the XML or JSON data sheet delivers the content. This is the recommended flow for a webshop or PIM that stores product content itself.

• Download the PIF (see section 7). If it has no product rows, stop and keep your previous version.
• Load it into a staging table, next to your previous version.
• Compare the two versions:

• Fetch each data sheet from the path(<language>) link (XML), or by its Icecat product ID (JSON, see section 5).
• Download the images, documents and videos referenced in the data sheet and host them yourself. Icecat file links are for downloading only: do not link to them from your shop pages, because they can stop working.
• Update your database. Use Your product ID, or Your product code + Your brand name, to find the right record.
• Save the new PIF as your “previous version” for the next run.

Because every product carries its own timestamp, you can run this flow daily, weekly or monthly and never miss a change.

Flow B: Icecat Live on your product pages, with the PIF deciding where to show it

Icecat Live HTML inserts the Icecat data sheet into your product page when the page loads, so you do not store any content. On its own, though, your shop does not know which of its products have Icecat content. The PIF fills that gap.

• Download the PIF every day (see section 7).
• For every product in your shop, look up its row in the PIF, using Your product ID or Your product code + Your brand name.
• Decide what to show:

• Call Icecat Live with the Icecat product ID from the PIF (see section 5), not with your own product code. Icecat has already matched the product, so spelling differences can no longer cause a miss.
• When a new row appears in the PIF, switch the block on for that product.

The result: a fast launch without your own content database, and no empty or broken content blocks for your shoppers.

Flow C: monitoring your coverage

Use the PIF to measure, and improve, how much of your assortment Icecat covers.

• Compare the number of product rows in the PIF with the number of products in your product file.
• Count the rows with a filled error_message, grouped by message. They show which products you could get with a different subscription or brand authorisation.
• Download the list of skipped products from your matching results. Check them for wrong or missing product codes, brands and GTINs, correct your file, and match again.
• Repeat monthly and follow the trend.

Related manuals

• Manual for Channel Partners: Icecat Product XML
• Manual for Channel Partners: Icecat Product JSON
• Manual for Channel Partners: XML Index Files
• Manual for Channel Partners: Icecat Live HTML
• Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth
• How to host your Product Feed