Akeneo integration with your online store: complete products, per channel and locale

What Akeneo is and who runs it

Akeneo is a product information management system (PIM): the place where product data is collected, enriched, translated and checked before it goes to a store, a marketplace or a print catalog. It was founded in 2013 in Nantes, France, and started as open source. Its users are manufacturers, brands and distributors with thousands of items in several languages.

For an integration, the edition decides two things: whether Akeneo reports changes itself, and whether assets and reference entities exist.

What connects to Akeneo

Akeneo owns what a product is: name, description, attributes, categories, variants and media. The ERP owns the item number, price and stock. That split decides the flows.

A product goes to the store only when it is complete for that store's channel and locale. Akeneo calculates completeness itself, and the integration filters on it with the completeness filter. A half-finished product stays in Akeneo until the team finishes it. How these flows fit together across systems is on the product data page.

How Akeneo exposes data

REST API through a connection

Akeneo has a REST API with JSON. Access runs through a connection created in the PIM. It gives four values: client ID, secret, username and password, and the password is shown once. With them the integration requests an access token valid for 3,600 seconds and a refresh token valid for 1,209,600 seconds, which is 14 days.

The limits

Akeneo's good practices for the REST API set these numbers. The limit of 10 concurrent calls applies to the whole instance: a marketplace feed, a print tool and our integration on the same PIM share those 10. We keep the integration at 4 and wait the number of seconds in Retry-After on a 429, as described in API throttling and backoff.

The arithmetic for a first load of 40,000 products: at 100 per page that is 40,000 / 100 = 400 requests; at the default page size of 10 it would be 4,000. With page paging Akeneo stops at page 100, because 100 x 100 = 10,000, so the integration pages with search_after. After the first load it asks only for products with updated later than the previous run. On SaaS those times are in UTC.

Batch writes answer per line

Writes from the ERP go to the batch endpoint as application/vnd.akeneo.collection+json: one product per line, at most 100 per request. The response is one status per line, so one bad line does not fail the batch:

{"line":1,"uuid":"fc24e6c3-...","status_code":204}
{"line":2,"uuid":"573dd613-...","status_code":422,
 "message":"Property \"group\" does not exist."}
{"line":3,"uuid":"25566245-...","status_code":201}

2,500 new items from the ERP are 25 requests. The integration reads every line, marks the 201 and 204 lines as done and puts each 422 on a list with its message. A PATCH merges objects and replaces everything else: sending categories with one code removes the product from all other categories.

UUIDs and events

Since November 2022 a product has a UUID and the identifier is optional. /api/rest/v1/products-uuid returns every product; the older /products silently skips products without an identifier.

The Event Platform sends events such as com.akeneo.pim.v1.product.updated, with 20 subscribers per PIM and 20 subscriptions per subscriber. The older Events API is supported until 31 December 2026. An event is a signal: the integration reads the product, checks completeness and keeps a polling pass on updated next to it, for the reasons in webhooks are not a guarantee.

Where an Akeneo integration gets stuck

Every value has a locale and a channel

An Akeneo value is never one field. Each one hangs on a locale, a scope (the channel), both or neither.

The color arrives as the code black; the label "Black" comes from a separate call on the attribute's options. The weight is an amount with a unit. The description exists per channel, so a second store on channel b2b gets different text, or none. The integration records per store which channel and which locales it reads, and what happens when a translation is missing. The field mapping note covers this class of mismatch.

Product models and variant axes

A family variant has 1 or 2 levels of variation, with at most 10 axes per level and 20 in total. A work shoe can vary on color at the first level and on size and width at the second. Stores are stricter: Shopify allows 3 options and 2,048 variants per product. Per family we decide how two levels and several axes are flattened into store options; the variants page has the cases.

Options and media

A select attribute returns codes. Options are created at 3 per second, so a supplier import that adds 1,200 new color codes takes 1,200 / 3 = 400 seconds, 6 minutes 40 seconds, before the products that use them can be written. Images are stored as a media file code, not a public URL. The integration downloads each file from /media-files/{code}/download with the token and uploads it to the store.

Platforms we integrate with Akeneo

The integration is built on your Akeneo: your families, channels, locales and completeness rules. What the receiving side needs is on each platform page:

• Shopify: 3 options per product, metafields for the attributes Shopify has no field for.
• Magento: configurable and simple products, attribute sets, values per store view.
• WooCommerce: variable products with global attributes, batches of 100 through the REST API.
• BigCommerce and Shopware.

Another PIM in place is covered on the Salsify page. We build the integration for a fixed price, then host, run and monitor it for a monthly fee. Before go-live it runs as a dry run: you see per product which title, options and images would land in the store, and nothing is published. Tell us which Akeneo edition and which store you run.