Akeneo Integration Known Limitations
This document describes the known limitations of the Akeneo integration with iPaaS.com. These limitations are inherent to the integration's current design and to Akeneo's REST API, and they apply to all subscribers regardless of catalog configuration.
This integration is built for Akeneo PIM (PaaS/SaaS editions), transferring product, product child data, and product category records to iPaaS.com with Akeneo as the source. It communicates with Akeneo by calling Akeneo's REST API at the subscriber's API Url, authenticating with the configured credentials to obtain an access token. It was built against Akeneo's documented production REST API endpoints (see the Akeneo API reference).
The integration supports both of Akeneo's product addressing schemes — the UUID-based product endpoint and the Identifier-based product endpoint — selected through the Akeneo Product ID Format subscription setting, so it can be pointed at either a UUID-based or an Identifier-based Akeneo catalog.
Not built for: This integration is not built for other PIM or vendor products, nor for a materially different future generation of the Akeneo API that changes the product, category, or association endpoints it relies on. Because Akeneo's product API has historically differed across versions, subscribers should validate the integration against their own Akeneo environment in a staging configuration before relying on it in production.
1. Standalone Variant Transfer Is Not Supported
Product variants are transferred only as children of their base product (the Akeneo Product Model). A variant — and its associated inventory, options, and related-product records — cannot be polled or manually synced on its own. When a variant needs to move to iPaaS.com, its parent product model is transferred and the variants are consolidated into that single parent transfer.
What this means for you: To update a variant in iPaaS.com, transfer its parent product. You cannot target an individual variant by itself through polling or Manual Sync. When you manually sync a variant product, enter the Product Code for the parent model; all of its variants transfer together.
2. Product ID Format Is Version- and Configuration-Dependent
Akeneo's product API identifies products either by UUID or by Identifier, and not every Akeneo version or catalog uses UUIDs. The Akeneo Product ID Format subscription setting controls which endpoint the integration reads from:
UUID — product reads and updates use Akeneo's UUID-based product endpoint (
/api/rest/v1/products-uuid/{uuid}).Identifier — product reads and updates use Akeneo's identifier-based product endpoint (
/api/rest/v1/products/{identifier}). This is the option for older Akeneo versions, or catalogs that identify products by a code rather than a UUID.
If this setting does not match your Akeneo environment, product reads and Manual Sync lookups fail.
What this means for you: Set Akeneo Product ID Format to match your Akeneo environment before transferring products, and confirm it during installation. If products are not reading from Akeneo, this setting is the first thing to check. The two supported options are UUID and Identifier only.
3. Polling Is Incremental
Automatic transfers run on a schedule through record polling (product and category poll events). Each polling cycle picks up only the records that have changed in Akeneo since the last saved poll timestamp — a "last modified date is greater than" filter, with the current time saved after each cycle for the next run. A record that has not changed since the last cycle is not re-sent.
What this means for you: Polling will not re-transfer unchanged records. To force a transfer of a record that has not changed — or to perform an initial load — use Manual Sync, or initialization for Product Categories. If you need to pull a large dataset (for example, a full catalog) at once rather than waiting for incremental polling, follow the iPaaS.com bulk-sync procedure using Postman: https://support.ipaas.com/en/articles/10488109-syncing-a-large-dataset-using-ipaas-com-and-postman-runner
4. Inventory Is a Proof-of-Concept
Akeneo has no native inventory feature. To demonstrate inventory transfer, the integration reuses standard Akeneo product attributes (main_inventory and east_inventory) as the stock figures and routes them to two fixed location names (MAIN and EAST). Each inventory collection looks up an existing iPaaS.com location by name and a location translation; it does not create locations. If no matching location is found, the inventory record is skipped rather than written to a default location.
What this means for you: Treat the supplied inventory and location mappings as an example to adapt, not a finished configuration. The locations referenced (MAIN, EAST) must already exist in iPaaS.com, with location translations in place, before inventory transfers. If your catalog stores stock under different attribute names, update the inventory mappings to match. Validate inventory behavior in a staging environment before relying on it in production.
5. Outbound Delete Is Not Supported
The integration covers Add and Update operations only. Deleting a product or category in Akeneo does not remove the corresponding record in iPaaS.com, and delete mappings are not included in the default templates.
What this means for you: Records removed in Akeneo remain in iPaaS.com until you remove them through another process. Plan any required cleanup of removed records separately; the integration will not delete them for you.
6. Related Products Require the Related Item and a Matching Association Type
A related-product association is transferred only when both conditions are met: the related item (product or variant) already exists in iPaaS.com, and the Akeneo association type code matches the configured filter (the supplied templates filter to UPSELL). Associations whose related item has not yet been transferred, or whose type code does not match the filter, are skipped. Akeneo association type codes are mapped to iPaaS.com related types through a Lookup Translation that the subscriber maintains.
What this means for you: Transfer the products and variants first so their related items exist in iPaaS.com before their associations are processed; subscribers running an initial load should transfer products before associations. To transfer association types other than UPSELL, adjust the association type code in the filter, and add a Lookup Translation entry for every association type code you intend to transfer. Validate this ordering in a staging environment before relying on it in production.
7. Categories Must Be Transferred Before Products
Products link only to categories that already exist in iPaaS.com. Category links on a product resolve only against categories that have already been transferred; unmatched category codes are skipped. Within the category hierarchy itself, a parent category must exist in iPaaS.com before a child can be linked to it.
What this means for you: Transfer your category structure first — using initialization on the Product Category collection, which orders parents before children — so that product-to-category links resolve when products transfer. If a product's category links are missing, confirm the categories were transferred before the product, then re-sync.
8. Placeholder Values to Replace Before Go-Live
The default templates ship with example, environment-specific values drawn from the iPaaS.com demo catalog. Each is flagged inline in the mapping documentation with a bold "Placeholder value — replace during implementation:" note. Replace every value below with the equivalent from your own Akeneo and iPaaS.com environments before enabling the affected collections.
Where | Placeholder value | Replace with |
Product Inventory (MAIN/EAST) — LocationId |
| Your iPaaS.com location names (Settings → Locations) |
Product Inventory (MAIN/EAST) — QtyAvailable and the mapping filters |
| The Akeneo attribute code(s) that hold your stock counts |
Related Product and Variant Related Product — mapping filter |
| Your Akeneo association type code(s), plus a Lookup Translation entry for each |
Product — Akeneo Product Media and Akeneo Test Image With Alt Text and Position |
| Your Akeneo asset attribute name and channel |
Product — Youtube Videos |
| Your Akeneo asset attribute and media-attribute code |
Product — Vimeo Videos |
| Your Akeneo asset attribute and media-attribute code |
Product — Channel VIsible B2B |
| Your Akeneo attribute and channel codes |
Product — Weight |
| Your Akeneo weight attribute code |
Product Category — category_date_scopable and category_date_scopable2 |
| Your Akeneo category attribute, channel, and locale |
What this means for you: Treat this as a pre-launch checklist. The values above are examples only and will not match a real subscriber catalog — leaving them in place causes records to be skipped (filters that never match) or attributes that never populate. This complements limitations 4 (inventory) and 6 (related products) above, which describe these in context, and the inline placeholder callouts in the mapping documentation.
This document lists 8 known limitations of the Akeneo integration. For limitation detail specific to an individual mapping collection — including per-collection caveats, filters, and field behavior — see the mapping collection descriptions for that collection. Transfer errors and skipped records can be reviewed under Dashboard / Integration Monitoring / Error Logs.