Summary
This documentation covers the Shopware Catalog Category family of mapping collections that flow category data from iPaaS.com into Shopware. The Add/Update Shopware Catalog Category FROM iPaaS.com collection creates or updates Shopware catalog categories from iPaaS.com category records, preserving the parent-child hierarchy and applying optional tags, while the companion Delete Shopware Catalog Category FROM iPaaS.com collection removes a Shopware category when the source category is retired in iPaaS.com. To avoid duplicate categories, the integration matches incoming categories against existing Shopware categories before creating new ones, and it automatically creates any missing ancestor categories so the full hierarchy exists before a child is linked.
ID Format
Manual Sync ID Format
For a manual sync, enter the iPaaS.com category record ID to transfer (or delete) a single category. The ID is the iPaaS.com identifier for the category record, for example 1024. Categories are also transferred automatically as a prerequisite when a product that references them is transferred, so a category is created in Shopware as needed to support its products.
External ID Format
After a category is created in Shopware, the integration saves the Shopware-assigned category identifier as the external ID linking the iPaaS.com category to its Shopware record, for example 3c604fa77a644e1e8727a622ca06067d. This external-id link is what later updates target, what the parent-resolution formula returns when placing a child under its parent, and what the Delete collection uses to find the Shopware category to remove.
Deleted Record Support
Outbound deletion is supported for this entity. The Delete Shopware Catalog Category FROM iPaaS.com collection removes a Shopware catalog category when a category delete is received from iPaaS.com. The deletion is keyed on the external-id link established when the category was first transferred: a category that was never transferred — and therefore has no link — has no Shopware target to delete. Deletions flow FROM iPaaS.com to Shopware only; there is no transfer of Shopware category deletions back to iPaaS.com.
Custom Field Support
The Add/Update collection supports custom fields. Category custom fields can be mapped to carry additional values into Shopware, and named custom fields drive specific features. The integration reads each custom field by its exact name using the GetCustomFieldValue helper, so the custom-field name configured on the source category must match the name referenced in the mapping exactly.
Shopware Category Tags: a comma-separated list of tag names applied to the Shopware category. The custom field must be named exactly Shopware Category Tags for the tags mapping to read it.
A subscription setting can also name a custom field as the basis for duplicate matching (see Shopware Caveats); when it does, the category must carry a custom field of that exact name, or the transfer fails.
When the Translations Enabled subscription setting is on, category content backed by custom fields is processed as multi-language translations.
Mapping Collection Status
Add/Update Shopware Catalog Category FROM iPaaS.com: Enabled. No mapping filter is applied, so all incoming category transfers are processed.
Delete Shopware Catalog Category FROM iPaaS.com: Enabled. No mapping filter is applied, so all incoming category delete requests are processed.
Trigger Events
Automatic (Webhook): Not available for either collection. Category records and deletions flow into Shopware from iPaaS.com; there are no Shopware-side webhook events that trigger these collections.
Manual Sync: Enter the iPaaS.com category record ID to transfer or delete a single category. Categories are also transferred automatically as a prerequisite when a product that references them is transferred.
Duplicate or Conflicting Mappings
Categories flow into Shopware FROM iPaaS.com only. There is no opposite-direction "TO iPaaS.com" catalog category collection in this integration, so there is no conflicting collection operating on the same records in the reverse direction and no circular-update risk. The Add/Update and Delete collections in this family cover different operations — create/update versus delete — and do not conflict with each other.
Shopware Caveats
Hierarchy and automatic parent creation: When a category has a parent, the integration ensures the parent category exists in Shopware before linking the child, automatically creating any missing ancestor categories. If a required parent category cannot be created, the transfer fails and an error is recorded in Dashboard / Integration Monitoring / Error Logs.
Duplicate detection and matching: Two subscription settings control how an incoming category is matched to an existing Shopware category to prevent duplicates. Product Category Duplicate Checking By selects the match basis: name (or blank) matches on the category name, description matches on the description, and any other value is treated as the name of a category custom field, in which case the integration matches on that named custom field. If that named custom field is missing on the category, the transfer fails — subscribers or their MiSP should ensure the named custom field exists on every category. Product Category Duplicate Matching By sets the Shopware field used for the comparison and defaults to name.
Translations: When the Translations Enabled subscription setting is on, category content backed by custom fields is processed as multi-language translations.
Deletion impact: Deleting a category in Shopware can affect its place in the catalog hierarchy and any products or subcategories assigned to it. Subscribers or their MiSP should confirm the impact on dependent records before deleting categories in production.
Name is required: Shopware requires a name to create a category. A transfer that arrives without a name is rejected and an error is recorded in Dashboard / Integration Monitoring / Error Logs.
iPaaS.com Caveats
iPaaS.com is the source of category data and delete requests in this integration; categories are authored and retired in iPaaS.com and transferred to Shopware.
In the template, the Shopware category name is populated from the iPaaS.com category description. Subscribers or their MiSP should confirm this matches how their category data is structured, and remap to the iPaaS.com category name if that is the intended source.
Category tags and duplicate-match custom fields are read by exact name. Subscribers or their MiSP should standardize these custom-field names in the source data so the intended features are enabled.
Because deletion relies on the external-id link, subscribers or their MiSP should ensure the category was transferred and linked before expecting a delete to succeed.
Subscribers should stagger large manual jobs and rely on the configured throttle limits to avoid overloading the Shopware API during mass transfers.
Setup Requirements
These collections transfer data FROM iPaaS.com TO Shopware. Automatic webhook transfer is not available for the catalog category family, so transfers are driven by Manual Sync or as a prerequisite when a referencing product is transferred. Subscribers or their MiSP configure category transfers through the Outbound Data Flows that move iPaaS.com category records into Shopware. No Shopware-side webhook subscription is required for these collections.
Integration Flow
A category transfer or delete is triggered from iPaaS.com — by Manual Sync with the iPaaS.com category record ID, or automatically when a product referencing the category is transferred.
The integration fetches the iPaaS.com category record.
For an Add/Update, the integration resolves the parent chain: when the category has a parent, it ensures the parent category exists in Shopware, automatically creating any missing ancestor categories first.
The integration checks for an existing matching Shopware category using the configured Product Category Duplicate Checking By and Product Category Duplicate Matching By settings to avoid creating a duplicate.
The category fields are transformed and written to Shopware — creating a new category or updating the matched one — including name, parent placement, product-display behavior, link type, and optional tags.
The integration saves the Shopware-assigned category identifier as the external ID linking the iPaaS.com category to its Shopware record (for example
3c604fa77a644e1e8727a622ca06067d).For a delete, the integration uses the external-id link to locate and remove the corresponding Shopware category.
Mappings
Add/Update Shopware Catalog Category FROM iPaaS.com
This collection creates or updates a Shopware catalog category from an iPaaS.com category record, preserving the parent-child hierarchy and applying optional tags.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Shopware) | Description |
Field | Description | Name | required — Sets the Shopware category name. In the template the source is the iPaaS.com category Description field; subscribers or their MiSP can remap this to the iPaaS.com category Name field if that better fits their data. A transfer with no name is rejected. |
Dynamic Formula | (parent resolution) | ParentId | optional — Places the category under its parent in the Shopware catalog hierarchy. When the category has a parent, the GetExternalIdAsync function resolves it to the linked Shopware category external ID. A category with no parent is created at the top level. |
Dynamic Formula | Shopware Category Tags (custom field) | CategoryTags | optional — Reads the Shopware Category Tags custom field and the StringListFromString function converts the comma-separated string into a list of tag names. Tags in the list are added, tags no longer present are removed, and returning nothing leaves existing tags unchanged. |
Static |
| DisplayNestedProducts | optional — Controls whether the category also displays products from its subcategories. The template sets this to true. |
Static |
| ProductAssignmentType | optional — Sets how products are assigned to the category. The template uses "product", meaning products are assigned directly. |
Static |
| LinkType | optional — Sets the category's link type. The template uses "page", presenting the category as a standard category page. |
Static |
| custom_testdaniyal_1 | optional — Writes a static value to a category custom field. This is example test data left in the template collection and is not part of the standard mapping set. Placeholder value — replace during implementation: "Test data from mappings" is test data; remove this mapping or replace its value during implementation. |
The ParentId formula:
if(ParentId > 0){
return await GetExternalIdAsync(ParentId, "Product Category", SpaceportSystemId);
}
//Set the default top level category here
//else {
// return "3c604fa77a644e1e8727a622ca06067d";
//}The commented-out block shows how to return a fixed top-level category ID when the category has no parent. Placeholder value — replace during implementation: the identifier 3c604fa77a644e1e8727a622ca06067d in the commented block is an example top-level category ID pinned to a specific Shopware store; if you uncomment this block, replace it with a valid top-level category ID from your target Shopware store.
The CategoryTags formula:
var value = GetCustomFieldValue(CustomFields, "Shopware Category Tags");
if (!string.IsNullOrEmpty(value)){
return StringListFromString(value);
}
return null;Delete Shopware Catalog Category FROM iPaaS.com
This collection deletes the Shopware catalog category linked to an iPaaS.com category when a delete request is received. It has no field mappings — it is a delete-by-link collection. When an iPaaS.com category delete is received, the integration deletes the matching Shopware category using the external-id link established when the category was first transferred, so no fields need to be mapped. A category that has no external-id link to a Shopware record has no target to remove, and the error is recorded in Dashboard / Integration Monitoring / Error Logs.
Error Handling
Errors surface in Dashboard / Integration Monitoring / Error Logs.
Missing required name: a category transfer arrives without a name. Shopware requires a name to create a category, so the transfer is rejected. Resolution: ensure the mapped source field (category description or name) is populated before transferring.
Missing duplicate-match custom field: Product Category Duplicate Checking By names a custom field that does not exist on the incoming category. The transfer fails. Resolution: ensure the named custom field exists on every category, or change the match basis to name or description.
Parent chain cannot be resolved: a required parent or ancestor category cannot be created. The transfer fails. Resolution: confirm the parent category data is transferable, then retry.
No external-id link on delete: a delete request targets a category that was never transferred and has no Shopware link. The request fails. Resolution: ensure the category was transferred and linked before expecting a delete to succeed.
Shopware API temporarily unavailable: the Shopware API is unreachable when a transfer or delete is triggered. The operation fails. Resolution: retry by triggering a new transfer or delete from iPaaS.com.
Testing & Validation
Test Scenarios
Transfer a new top-level category (no parent) by Manual Sync and confirm it is created at the top level in the Shopware catalog.
Transfer a category with a parent and confirm the integration places it under the correct Shopware parent, automatically creating any missing ancestor categories first.
Transfer a category whose source is missing the mapped name value and confirm the transfer is rejected with an error in Dashboard / Integration Monitoring / Error Logs.
Transfer a category twice and confirm the configured duplicate-match settings cause the second transfer to update the existing Shopware category rather than create a duplicate.
Transfer a category carrying a populated Shopware Category Tags custom field and confirm the tags appear on the Shopware category; remove a tag from the source and confirm it is removed in Shopware.
Delete a previously transferred category by Manual Sync and confirm the linked Shopware category is removed.
Issue a delete for a category that was never transferred and confirm the request fails with an error in Dashboard / Integration Monitoring / Error Logs.
Validation Checklist
The category name in Shopware matches the intended source field (description or name) after transfer.
Parent-child placement in the Shopware catalog hierarchy matches the iPaaS.com hierarchy, with no orphaned categories.
Duplicate matching uses the configured Product Category Duplicate Checking By and Product Category Duplicate Matching By settings and does not create duplicate categories.
Category tags reflect the Shopware Category Tags custom field, including additions and removals.
The example custom_testdaniyal_1 mapping has been removed or repurposed before production use.
The external-id link is saved after the first transfer so updates and deletes target the correct Shopware record.
Deletions remove the correct Shopware category and dependent-record impact has been reviewed.
Additional Notes
Categories transfer FROM iPaaS.com to Shopware only; there is no transfer of Shopware categories back to iPaaS.com.
Duplicate detection relies on the configured match basis (name, description, or a named custom field). Inconsistent naming or a missing match custom field in the source data can cause duplicate categories or a failed transfer; subscribers or their MiSP should validate the match configuration in a staging environment before relying on it in production. These limitations apply at the time this documentation was written.