Akeneo to iPaaS.com Product Category Mapping Documentation
Akeneo product categories can be transferred to iPaaS.com through initialization, scheduled record polling, or on-demand Manual Sync. Categories are created or updated in iPaaS.com from Akeneo category data, preserving the parent/child hierarchy so the iPaaS.com category tree mirrors Akeneo.
ID Format
When manually transferring an Akeneo product category on the iPaaS.com Manual Sync page, enter the category code in the iPaaS.com field — for example, master.
External ID Format
After a successful transfer, iPaaS.com saves the Akeneo category code as the external ID on a dedicated external-ID record for the category. That external-ID record is the primary match used to route subsequent updates to the same iPaaS.com category rather than creating a duplicate.
Deleted Record Support
Outbound delete is not supported for categories. Deleting a category in Akeneo does not remove the corresponding record in iPaaS.com, and delete mappings are not included in the default templates. These mappings cover Add/Update only.
Custom Field Support
Beyond the standard Name, Code, and Parent, Akeneo categories can carry category attributes — additional fields configured on your categories (for example, a category description, a banner image reference, or a marketing flag). These attribute values can be transferred into iPaaS.com custom fields.
Category attributes are read from the values array of the Akeneo category record (GET /api/rest/v1/categories/{code}). For each attribute you want to transfer:
Create a custom field in iPaaS.com and map the Akeneo category attribute to it. The attribute's value name is used as the custom field name, and the attribute's data value is stored as the custom field value.
Reference the attribute by the exact attribute name as it appears in the Akeneo API response (for example, description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US), not by its display label. Category attribute names are unique to each catalog and frequently carry a channel and locale qualifier.
Values are retrieved using the GetValueFromCategoryValues conversion function, which can filter by locale and channel (scope) and optionally strip HTML from rich-text attributes.
The two mappings in the table below (category_date_scopable and category_date_scopable2) are examples of this capability — one mapped as a direct field reference and one using the GetValueFromCategoryValues formula to pin a specific channel and locale. Confirm your own category attribute names in Akeneo, and validate the result in a staging environment before relying on it in production.
Mapping Collection Status
Status: Enabled. The collection has no mapping filter applied, so all categories are processed.
Trigger Events: Create and Update, via initialization, scheduled record polling (category/poll), and Manual Sync.
Supported Child Collections
None. The Product Category collection is a standalone root collection with no child collections.
System Caveats
Akeneo Caveats
Category name source: The category Name is taken from the Akeneo category's English (United States) label. If your catalog publishes category labels in other languages, validate the result in a staging environment before relying on it in production.
Custom category attributes are catalog-specific: Custom attribute mappings reference the exact Akeneo attribute name, including any channel/locale qualifier (for example,
category_date_scopable|...|b2b|en_GB). Confirm the exact attribute name, channel, and locale in your own Akeneo environment.
iPaaS.com Caveats
Transfer categories before products: Products link only to categories that already exist in iPaaS.com. Transfer the category structure first so product category links resolve.
Parent before child: A category's parent must exist in iPaaS.com before the child can be linked. Initialization transfers categories in the required order to preserve parent relationships; if you transfer individual categories manually, sync parents before their children.
Integration Flow
Initialization transfers all Akeneo categories to iPaaS.com in the required order to preserve parent relationships — useful for the initial load before products are integrated.
On each polling cycle, iPaaS.com requests the categories changed since the last saved poll timestamp (category/poll) and creates or updates them.
Categories can also be transferred on demand from the iPaaS.com Manual Sync page using the category code.
For each category, the Name, Description, and ParentId are set from Akeneo, and the parent code is resolved to the corresponding iPaaS.com category to build the hierarchy. Transfer errors and skipped records can be reviewed under Dashboard / Integration Monitoring / Error Logs.
Mappings
Add/Update Akeneo Product Category TO iPaaS.com
Mapping Type | Source Field (Akeneo) | Destination Field (iPaaS.com) | Description |
Field | Name | Name | Required. Copies the Akeneo category display name (the English/United States label) into the iPaaS.com category Name field. |
Field | Code | Description | Recommended. Copies the Akeneo category code — the unique system identifier of the category (for example "accessories" or "master") — into the iPaaS.com category Description field. Always present on every category. |
Field | Parent | ParentId | Establishes the category hierarchy by linking each category to its parent. In Akeneo a category records its parent using the parent category's code, which is resolved to the corresponding iPaaS.com category. |
Field | category_date_scopable|...|b2b|en_GB | category_date_scopable | Optional custom field. Copies a custom Akeneo category attribute value directly into iPaaS.com. The source field name includes the attribute's channel and locale qualifier; confirm the exact name in your Akeneo environment. Placeholder value — replace during implementation: The attribute name (including its channel/locale qualifier) is an example from the demo catalog; replace it with your own Akeneo category attribute. |
Dynamic Formula |
| category_date_scopable2 | Optional custom field. Reads a single custom Akeneo category attribute value with a formula, pinning down a specific channel (b2b) and locale (en_GB). Use this approach when you need a specific language/channel variation, or when the attribute name contains characters awkward to enter as a plain field reference. Placeholder value — replace during implementation: The attribute reference (a specific attribute UUID with the b2b channel and en_GB locale) is an example from the demo catalog; replace it with your category attribute, channel, and locale. |
Bulk Initialization
After completing the category mappings, you can run a bulk initialization to transfer all Akeneo product categories into iPaaS.com at once, in the order required to preserve parent relationships. This is beneficial when categories need to be in place before product data is integrated. To start it, use the initialization control next to Product Category in iPaaS.com. Bulk initialization is only necessary for subscribers who integrate product categories; if you are not using categories, it is not required.
Known Limitations
Polling is incremental. Each polling cycle only picks up categories changed since the last saved poll timestamp. Use Manual Sync or initialization to force a transfer of unchanged categories.
Outbound delete is not supported — see Deleted Record Support above.
Error Handling
Category not linked to its parent — Occurs when the parent category has not yet been transferred to iPaaS.com. Resolution: transfer the parent first (or run bulk initialization, which orders parents before children), then re-sync.
Custom attribute value not populated — Occurs when the referenced Akeneo attribute name, channel, or locale does not match the category's data. Resolution: confirm the exact attribute name/channel/locale in Akeneo and update the mapping.
Transfer errors and skipped records are visible under Dashboard / Integration Monitoring / Error Logs.
Testing & Validation
Test Scenarios
Create a new category in Akeneo and verify it transfers to iPaaS.com (via polling or Manual Sync using the category code) with Name, Description, and ParentId populated.
Update a category name in Akeneo and confirm the change propagates to the existing iPaaS.com category without creating a duplicate.
Create a parent category and a child category and verify the hierarchy is preserved in iPaaS.com (the child's ParentId resolves to the parent).
Run bulk initialization and confirm all categories transfer in parent-before-child order.
Validation Checklist
The Name and ParentId mappings resolve for every category transferred.
Parent categories exist in iPaaS.com before their children (or initialization is used).
Custom category attribute names match the Akeneo channel/locale qualifiers in your environment.
Error Logs (Dashboard / Integration Monitoring / Error Logs) show no unexpected skipped or failed records after a test sync.