ICECAT – Akeneo connector – Documentation v3.1

Owner: CTO / TechOps Officer
Last update: 07-04-2026
Scope: A clear, end‑to‑end explanation of how Icecat pushes data into a client’s Akeneo PIM, from scoping to production, with a detailed workflow, API examples, and a diagram.

Introduction

The Icecat Connector is a product data delivery solution that automatically enriches your catalog with accurate content for 27 million products in 60+ languages. Made by the Icecat technical team.

The Connector updates your catalog with Icecat content as soon as product identifiers are added to Akeneo. This automated system keeps your product data current without requiring manual intervention or additional tools.

The Connector operates independently, monitoring the Akeneo instance for activity and detecting changes that require product updates. If the requested product data is not immediately available, the system starts data creation tasks and delivers the content as soon as it is obtained from official manufacturer feeds.

This self-contained service simplifies product data synchronization, ensuring your catalog remains up to date and accurate.

1. Executive Summary

The Icecat Connector is a product‑content enrichment service that feeds Akeneo with Icecat data. There are three mapping options:

Mapping on the Icecat platform performed by Icecat.
Mapping on the Icecat platform operated by the client → Icecat provides onboarding and access to the Icecat mapping tool.
Mapping inside Akeneo (client‑side). In this case, Icecat pushes data in the Icecat taxonomy, and the client transforms it within Akeneo. Heads up: we can’t confidently advise this one due to the lack of a multi-taxonomy feature inside Akeneo.

The project is split into two phases:

– Pre‑production (mandatory if mapping is done on the Icecat side): taxonomy collection, filter definitions, mapping rules/completeness, and API technical tests.

– Production: daily refresh of the list of products to push, then incremental (partial) PATCH to Akeneo.

2. Workflow Diagram

3. Pre‑production

3.1 Client‑provided prerequisites

Akeneo URL (dev + prod if possible).
API credentials (username, password, clientId, clientSecret). To enable API functionality, these credentials must be linked to a role granting the necessary access rights.
Access to read, write, create:

/api/rest/v1/attributes/

/api/rest/v1/products/

Akeneo UI account (read/write as needed) for manual spot checks.
Shared the languages included in their agreement
Access to full taxonomy: categories, families, attributes (features), option lists, formats, brands -> Provided via Akeneo API or Excel/CSV.
Enrichment list to create on Akeneo
If mapping isn’t managed by Icecat: what is the format of attributes name that they want to receive. Example:
Attribute Name: IC_Image formats supportedDE
Example Data: BMP | GIF | JPEG | MPO | PNG | WEBP

3.2 Product eligibility filters

Define GET filters to list products to enrich (e.g., data_owner = “icecat”, by family, channels, locales, status).
They drive which products are pushed and when runs are executed.

3.3 Mapping choices

Mapping on the Icecat platform: performed by Icecat or by the client. If done by the client, Icecat provides onboarding to the mapping tool (transformation rules, value dictionaries, sample tests).
Mapping in Akeneo (client‑side): Icecat pushes in Icecat taxonomy; the client converts it within Akeneo (internal rules/automations).

3.4 Technical tests

Validate OAuth2 auth, quotas, PATCH formats, locales/scopes, batch sizes, media handling, encodings (UTF‑8).
Set retry thresholds, back‑off, logging strategy, and the reporting model.

4. Production – Orchestration

4.1 Daily refresh of the product list

Scheduled job (e.g., daily, with ad‑hoc runs).
Akeneo GET /api/rest/v1/products with search filters + pagination.
De‑duplication, comparison vs previous pushes, detection of deltas (obsolete fields, new/changed fields).

4.2 Payload preparation

Normalize attributes / locales / scopes.
Handle media (remote URL vs binary upload).
Idempotency: partial PATCH only on Icecat‑owned fields—never break ongoing client work.

4.3 PATCH to Akeneo + error handling

Controlled batch size (e.g., 50–200 products, depending on limits).
Line‑by‑line analysis of responses: 204/201 success, 422 errors.
Targeted retries for transient errors (timeouts, 5xx) with exponential back‑off.
Group 422 by cause (missing attribute, type/format, locale) for corrective actions.

4.4 Reporting & Observability

Reports available on the Icecat Platform: success/failure.
Optional Excel exports and dashboards.

5. Akeneo API Details (examples)

Note: Examples illustrate common patterns (Akeneo 5/6/7). Adapt to your exact instance.

5.1 OAuth2 Authentication

Endpoint: POST /api/oauth/v1/token

Option A – Password grant (for POCs / secured envs)

curl -X POST \
-u “<clientId>:<clientSecret>” \
-H ‘Content-Type: application/json’ \
-d ‘{
“grant_type”: “password”,
“username”: “<api_username>”,
“password”: “<api_password>”
}’ \
https://<tenant>.akeneo.com/api/oauth/v1/token

Response (excerpt)

{
“access_token”: “eyJ…”,

“expires_in”: 3600,
“token_type”: “bearer”,
“scope”: null,
“refresh_token”: “def…”
}

Option B – Refresh token

curl -X POST \
-u “<clientId>:<clientSecret>” \
-H ‘Content-Type: application/json’ \
-d ‘{
“grant_type”: “refresh_token”,
“refresh_token”: “<refresh_token>”
}’ \
https://<tenant>.akeneo.com/api/oauth/v1/token

5.2 List products to enrich

Endpoint: GET /api/rest/v1/products

Example filter: data_owner IN [“icecat”]

curl -G \
-H ‘Authorization: Bearer <access_token>’ \
-H ‘Content-Type: application/json’ \
–data-urlencode ‘search={“data_owner”:[{“operator”:”IN”,”value”:[“icecat”]}]}’ \
–data-urlencode ‘limit=100’ \
https://<tenant>.akeneo.com/api/rest/v1/products

Considerations: – Use pagination (page/limit or search_after depending on version).
– Add criteria as needed: family, enabled, updated >[date], locales, completeness.

5.3 Push products – bulk PATCH (collection)

Endpoint: PATCH /api/rest/v1/products
Header: Content-Type: application/vnd.akeneo.collection+json

Payload: NDJSON (1 JSON row per product)

PATCH /api/rest/v1/products HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/vnd.akeneo.collection+json

{“identifier”:”5702017566733″,”values”:{“name”:[{“locale”:”en_US”,”scope”:null,”data”:”LEGO Starfighter”}],”description”:[{“locale”:”en_US”,”scope”:”ecommerce”,”data”:”…”}]}}
{“identifier”:”5702017584195″,”values”:{“brand”:[{“locale”:null,”scope”:null,”data”:”LEGO”}]}}
{“identifier”:”5702017588025″,”values”:{“image”:[{“locale”:null,”scope”:”ecommerce”,”data”:{“_link”:”https://cdn.icecat.biz/img/xyz.jpg”}}]}}

Line responses:

{“line”:1,”identifier”:”5702017566733″,”status_code”:204}
{“line”:2,”identifier”:”5702017584195″,”status_code”:204}
{“line”:3,”identifier”:”5702017588025″,”status_code”:201}

Errors:

{“line”:4,”identifier”:”0196337820449″,”status_code”:422,
“message”:”Validation failed: Attribute ‘name’ expects text, got number”}

5.4 Single‑product PATCH

Endpoint: PATCH /api/rest/v1/products/{identifier}
Header: Content-Type: application/jsoncurl -X PATCH \
-H ‘Authorization: Bearer <access_token>’ \
-H ‘Content-Type: application/json’ \
-d ‘{
“values”: {

“name”: [ { “locale”: “fr_FR”, “scope”: null, “data”: “LEGO Chasseur” } ],
“description”: [ { “locale”: “fr_FR”, “scope”: “ecommerce”, “data”: “…” } ]
}
}’ \
https://<tenant>.akeneo.com/api/rest/v1/products/5702017566733

5.5 Product media (as needed)

Upload: POST /api/rest/v1/media-files (multipart binary) → returns a media code.
Link to the product via values with data = media code, or via _link when the attribute supports a remote URL.

6. Data model & conventions

Locales & Scopes: any localized/channel attribute must set locale and/or scope.
Types: strictly follow Akeneo types (text, number, single/multi‑option, price, metric, boolean, date).
Options: for option attributes, the internal option key must exist (else: create it or map to an existing value).
Idempotency: Icecat updates only the fields it owns (e.g., data_owner=icecat).

7. Errors & recovery

422 Validation failed: log the exact message, group by attribute/cause, fix mapping/format, then retry.
401/403: check token expiry, API role permissions, refresh token.
5xx/timeout: retry with exponential back‑off, reduce batch size.
Functional conflicts: if the client edits an Icecat‑managed field, set a conflict policy (last write wins, locked field, mirror field, etc.).

8. Implementation plan

8.1 Pre‑production (2–30 days depending on scope)

Taxonomy collection (API or Excel).
Filter setup (target products, locales/scopes, channels).
Mapping choice (+ transformation rules if Icecat‑side).
API tests (auth, GET listing, single & bulk PATCH, media).
Reporting model (access on Icecat Platform, export/dashboards if needed).

8.2 Production (iterative)

Daily refresh of the product list to push.
Payload generation (delta‑only).
Product PATCH.
Monitoring via the Icecat Platform (reports).

9. Practical filter examples

By owner: {“data_owner”:[{“operator”:”IN”,”value”:[“icecat”]}]}
By family: {“family”:[{“operator”:”IN”,”value”:[“laptops”,”phones”]}]}
Active products FR: {“enabled”:[{“operator”:”=”,”value”:true}],”completeness”:[{“operator”:”>=”,”value”:90,”scope”:”ecommerce”,”locale”:”fr_FR”}]}
Recently updated: {“updated”:[{“operator”:”>”,”value”:”2025-08-01T00:00:00Z”}]}

10. Appendices – Ready‑to‑use snippets

10.1 GET products (curl) with multiple filters

curl -G \
-H ‘Authorization: Bearer <access_token>’ \
–data-urlencode ‘search={
“data_owner”:[{“operator”:”IN”,”value”:[“icecat”]}],
“enabled”:[{“operator”:”=”,”value”:true}],

“family”:[{“operator”:”IN”,”value”:[“laptops”,”phones”]}]
}’ \
–data-urlencode ‘limit=100’ \
https://<tenant>.akeneo.com/api/rest/v1/products

10.2 NDJSON template for bulk PATCH

{“identifier”:”SKU-001″,”values”:{“name”:[{“locale”:”fr_FR”,”scope”:null,”data”:”Nom FR”}]}}
{“identifier”:”SKU-002″,”values”:{“name”:[{“locale”:”en_US”,”scope”:null,”data”:”Name EN”}]}}

10.3 Multi‑option attribute example

{
“values”: {
“color”: [{“locale”: null, “scope”: null, “data”: “black”}],
“connectivity”: [{“locale”: null, “scope”: null, “data”: [“wifi”,”bluetooth”]}]
}
}

Contacts & Support

Icecat TechOps: coordination, mapping, run supervision.
Client: Akeneo functional ownership (governance of attributes, families, locales, internal workflows).

KINDLY COMPLETE ALL OF THE BELOW INFORMATION

BEFORE STARTING DATE OF YOUR PROJECT

Akeneo URL (dev + prod)

DEV:…………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………PROD:………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………

API credentials (username, password, clientId, clientSecret). To enable API functionality, these credentials must be linked to a role granting the necessary access rights.

………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………

Access to read, write, create:

/api/rest/v1/attributes/

YES IT GIVEN ? Y / N

/api/rest/v1/products/

YES IT GIVEN ? Y / N

Akeneo UI account (read/write as needed) for manual spot checks.

YES IT GIVEN ? Y / N

Shared the languages included in your current agreement

……………………………………………………………………………………………………………………………………..………………….

Access to full taxonomy: categories, families, attributes (features), option lists, formats, brands -> Provided via Akeneo API or Excel/CSV.

YES IT GIVEN ? Y / N

Enrichment list to create on Akeneo

YES IT CREATED? Y / N

If mapping isn’t managed by Icecat: what is the format of attributes name that they want to receive. Example:
Attribute Name: IC_Image formats supportedDE
Example Data: BMP | GIF | JPEG | MPO | PNG | WEBP

Read further: Icecat, akeneo, e-commerce, ecommerce, Icecat

icecat

Icecat is a global leader in product content syndication, helping brands, manufacturers, distributors, and retailers deliver enriched and consistent product information across multiple platforms. Trusted by 40,000+ e-commerce brands, Icecat helps turn browsers into buyers.