Summary

commercetools categories can be created and updated from iPaaS.com Product Category records through the Add/Update commercetools Product Category FROM iPaaS.com mapping collection. Each category is written with its name, slug, description and key, together with a reference to its parent category, so that a multi-level taxonomy maintained upstream of iPaaS.com arrives in commercetools with its hierarchy intact. Transfers run automatically once the relevant outbound subscriptions are enabled, and are available at any time through Manual Sync.

ID Format

Manual Sync ID Format

This collection transfers data from iPaaS.com, so the identifier entered on the iPaaS.com Manual Sync page is an iPaaS.com identifier, not a commercetools one.

Enter the iPaaS.com Product Category identifier — the numeric identifier of the Product Category record, shown on the record in iPaaS.com. It is a whole number with no prefix, no separator and no hyphens. It is not a commercetools GUID, and entering a commercetools identifier here will not resolve to a record.

The integration uses that identifier to retrieve the full iPaaS.com category record and write it to commercetools.

External ID Format

After a successful Add, iPaaS.com stores the identifier that commercetools returned for the new category as the external-ID link on the iPaaS.com Product Category record. The value stored is a commercetools identifier even though the transfer runs from iPaaS.com.

commercetools issues record identifiers as 36-character GUIDs (UUIDs) — 32 hexadecimal characters in five hyphen-separated groups, in the shape xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Identifier values are specific to each commercetools project, so no sample value is published here; read the value from the iPaaS.com Product Category record after the first successful transfer.

That stored link does two things. It routes every subsequent transfer of the same category to an update of the existing commercetools category rather than creating a duplicate, and it is the value this collection's mapping filter reads when deciding whether a category's parent is already present in commercetools.

Deleted Record Support

Outbound delete is not supported. This integration does not delete commercetools categories in any direction. Delete mappings are not included in the default mapping templates, and a category removed in iPaaS.com does not propagate as a deletion to commercetools — the commercetools category remains in place. An attempted delete fails with the message "The method or operation is not implemented." — the exact string to search for in the Error Logs.

Categories that must be removed have to be deleted directly in commercetools.

Custom Field Support

This integration has no custom-field implementation. There is no custom-field configuration surface for this collection, and no conversion function is provided for reading or writing custom-field values on a category. Data that is not covered by the fields listed under Mappings cannot be carried into commercetools by this collection.

Mapping Collection Status

Status: Enabled.

Trigger Events: The iPaaS.com outbound subscription scopes category/product/created and category/product/updated drive this collection. Subscribers or their MiSP enable them under Outbound Data Flows in the subscription configuration — see Connections and Settings and the Installation Instructions.

No automatic transfers occur until those subscriptions are enabled. Enabling them is a deliberate configuration step, not a default. Until then, categories transfer only through Manual Sync, which is available on this collection regardless of whether any outbound subscription is enabled.

Whether a given transfer creates a new commercetools category or updates an existing one is decided by whether iPaaS.com already holds an external-ID link for that category — not by which scope raised the event. A category that has never been linked is created; a category that carries a link is updated.

Bulk initialization of existing commercetools categories is not supported.

Duplicate or Conflicting Mappings

No other mapping collection in this integration writes commercetools product categories, and there is no inbound collection that brings commercetools categories into iPaaS.com. This collection is the only category flow in either direction.

Relationship to Product Category Assignment

Category assignment — the link between a product and the categories it belongs to — is handled separately, by the categories mapping on Add/Update commercetools Product FROM iPaaS.com. That mapping resolves iPaaS.com categories to the commercetools categories this collection created, using the formula function ConvertCategoriesToCommerceToold, which is supplied by the integration and selectable in the mapping editor. The function name is misspelled and appears that way in the mapping-formula picker; it is shown here exactly as subscribers will see it on screen.

The two collections are complementary rather than conflicting: this collection creates the categories, and the Product collection attaches products to them. The practical consequence is an ordering one — transfer the category taxonomy before publishing the product catalogue, so products have categories to be assigned to.

Duplicate Detection

This integration implements no duplicate detection, no match fields and no conflict-resolution methods for any collection. Duplicate avoidance rests entirely on the external-ID link described under External ID Format. If a matching category already exists in commercetools but has never been linked through iPaaS.com, this collection creates a second category rather than detecting and reusing the existing one. Categories created outside the integration will not be adopted.

Supported Child Collections

None. This is a root collection with no dependent child collections. The category record is written in a single transfer with no child records of its own. The parent/child relationship this collection carries is between categories in the taxonomy, not between mapping collections.

System Caveats

commercetools Caveats

Category key and slug are constrained. commercetools restricts both values to a limited character set and a maximum length. The values this collection derives are reduced to letters, digits, hyphens and underscores for that reason. Where a category name is long, or the taxonomy is deeply nested, the derived value can exceed the length commercetools accepts and the transfer is rejected. Subscribers with long category names or deep trees should validate the derived values in a staging environment before relying on them in production, and adjust the derivation mappings if the limit is reached.
Slug uniqueness. commercetools treats the category slug as a unique value within a project. Two categories that derive to the same slug cannot both exist; the second write is rejected. Including the parent trail in the derivation is what normally prevents this, but two identically named categories sitting in identically named branches can still collide.
Record versioning. Every update is applied against the category's current record version, which the integration reads immediately before writing. If the same commercetools category is edited elsewhere between that read and the write, the write is rejected as out of date and the transfer fails. Re-running the transfer resolves it.
Category quota. commercetools publishes its per-project quotas at https://docs.commercetools.com/api/limits (retrieved 2026-07-20). That page gives the category quota as 10,000 categories per project, and states the limit is configurable per project rather than absolute. Subscribers with taxonomies approaching that figure should confirm their project's current limit with commercetools before a bulk transfer.
Rate limiting. This documentation makes no claim that a request declined for a rate limit is retried, rescheduled or resumed on the subscriber's behalf. Treat a declined request as a failed transfer: monitor Dashboard / Integration Monitoring / Error Logs, re-run affected records with Manual Sync, and validate throughput for large taxonomies in a staging environment before relying on it in production.

iPaaS.com Caveats

Parent ordering is enforced by rejection, not resolved for you. The mapping filter on this collection rejects a child category whose parent has not yet been transferred, with the message Parent category must be uploaded first. iPaaS.com does not queue the parent, retry the child, or transfer the parent on the child's behalf. There is no automatic dependency transfer in this integration. A failed child transfer must be re-run manually after its parent has been transferred successfully. See Mapping Filter under Mappings.
Category names shorter than three characters can fail on update. The update path derives an internal comparison value by reading the first three and the last two characters of the category name. A category whose name is shorter than three characters can therefore fail on update. Subscribers should validate short category names in a staging environment before relying on them in production.
An empty description value fails on update. The update path reads the incoming description in order to compare it against the value already stored on the commercetools category, so a category updated with no description value fails rather than transferring without one.
The connection test reports success without contacting commercetools. A configuration problem in the connection settings will not be caught by the test — it appears at the first transfer instead, as an authorization failure in Dashboard / Integration Monitoring / Error Logs. Validate the connection settings by running a single Manual Sync rather than by relying on the test result. See Connections and Settings.
Field references in dynamic formulas use PascalCase on the iPaaS.com source side, matching the iPaaS.com field names shown in the mapping editor.

Integration-Specific Caveats

This collection compares before it writes. On update, each change instruction is built and then removed when the incoming value already matches the value stored on the commercetools category, so only genuinely changed values are sent. As a result no unmapped-field overwrite risk applies to this collection — it does not silently clear category fields that are left unmapped. The failure mode here is the opposite one: because the comparison reads the incoming value, a field left unmapped causes the transfer to fail with an error rather than to erase data. Both outcomes are avoided by keeping the full field set mapped.
Key and slug are derived, not copied. Both values are built from the category name together with its position in the category tree, then reduced to letters, digits, hyphens and underscores. This is deliberate: commercetools constrains what these two values may contain, and deriving them from the tree trail is what keeps them unique across a taxonomy in which two different branches may hold categories of the same name.
The description is sourced from the category name. The shipped default mapping for description_enUS reads the iPaaS.com category name, not a description field. Every category therefore arrives in commercetools with its name repeated as its English description. Populating a separate description value in iPaaS.com has no effect under the default mappings — the mapping must be repointed at that field first.

Setup Requirements

iPaaS.com Configuration

Enable the outbound subscriptions. Where the automatic path is wanted, enable category/product/created and category/product/updated under Outbound Data Flows in the subscription configuration. Until they are enabled, categories transfer only through Manual Sync. The full walkthrough is in the Installation Instructions.
Populate a name on every category. Each iPaaS.com Product Category intended for transfer must carry a name. Under the shipped default mappings the name also supplies the category description and the derived key and slug, so a category with no name cannot transfer.
Decide the description behavior before go-live. Where genuine category descriptions are maintained in iPaaS.com, repoint the description_enUS mapping at that field before the first production transfer, and ensure the chosen field is populated on every category — an empty description value fails on update.

commercetools Configuration

Complete and valid connection settings. The commercetools connection settings must be in place before the first transfer. Because the connection test always reports success, confirm them with a single Manual Sync rather than by relying on the test result. Credential details are covered in Connections and Settings.
Confirm the project category quota where the taxonomy is large — see commercetools Caveats.

Transfer Ordering

Parent categories must be transferred before their children. Transfer the taxonomy from the top downward: root categories first, then each successive level. This integration does not transfer a missing parent automatically and does not retry the child. A child transferred ahead of its parent is rejected and must be re-run after the parent succeeds. This ordering is the single most common cause of failed category transfers.
Transfer the category taxonomy before publishing the product catalogue, so that products have categories to be assigned to.

Integration Flow

A transfer is dispatched — either automatically, from an enabled category/product/created or category/product/updated subscription under Outbound Data Flows, or manually, by entering the iPaaS.com Product Category identifier on the Manual Sync page.
iPaaS.com retrieves the full Product Category record and applies the collection's mappings, producing the name, slug, description, key and — for a child category — the parent reference.
The mapping filter runs before any write. It looks up whether the category's parent has already been transferred to commercetools. A top-level category passes; a child whose parent is already present passes; a child whose parent is not yet present is rejected here, and nothing is written. The parent is not fetched or transferred on the child's behalf.
iPaaS.com checks whether it already holds an external-ID link for this category. This determines whether the transfer creates or updates.
New category (Add). The category is created in a single write carrying the name, slug, description, key and — where one exists — the parent reference. The integration then re-reads the saved category to return its stored state.
Existing category (Update). The integration first reads the current commercetools category to obtain its record version, then builds change instructions for name, description, slug and key. Each instruction is compared against the value already stored on the commercetools category and removed when the two match, so only genuinely changed values are sent. The integration then re-reads the saved category.
On a successful Add, iPaaS.com stores the commercetools category identifier as the external-ID link on the iPaaS.com Product Category record — a 36-character GUID, as described under External ID Format. That link routes every later transfer of the same category to the update path, and it is the value step 3's filter reads for any child of this category.
On failure, the error is recorded in Dashboard / Integration Monitoring / Error Logs. Nothing is retried automatically. The record can be re-run with Manual Sync once the cause is resolved.

Mappings

Add/Update commercetools Product Category FROM iPaaS.com

iPaaS.com data type: Product Category

Sync type: Add/Update

Mapping Filter

var external = await GetExternalIdAsync(ParentId, "Product Category", SpaceportSystemId);
if(IsEmpty(ParentId))
  return true;
else if(!IsEmpty(ParentId) && IsEmpty(external))
  throw new Exception("Parent category must be uploaded first");
else return true;

Filter Description. The filter runs before any category is written to commercetools. It first reads ParentId — the iPaaS.com identifier of the category's parent — and looks up external, the commercetools link that iPaaS.com stored when that parent was itself transferred. It then resolves one of three ways:

Top-level category — passes. Where ParentId is empty, the category has no parent. IsEmpty(ParentId) is true, the filter returns true, and the category is written to commercetools as a root-level category.
Child category whose parent is already in commercetools — passes. Where ParentId carries a value and external also carries a value, the parent has already been transferred and its commercetools link is available. Neither rejection condition applies, the filter returns true, and the category is written beneath its parent.
Child category whose parent has not yet transferred — rejected. Where ParentId carries a value but external is empty, the parent has never been transferred to commercetools and there is no link to resolve. The filter raises an error carrying the message Parent category must be uploaded first, and the category is not written. That message appears verbatim in Dashboard / Integration Monitoring / Error Logs and can be searched for directly.

This third branch is an ordering requirement enforced by rejection — it is not an automatic dependency transfer. The filter checks for the parent's link; it does not create one. This integration does not fetch the missing parent, does not transfer it on the child's behalf, and does not queue or retry the rejected child. Subscribers or their MiSP must transfer parent categories before their children, working from the top of the taxonomy downward, and re-run any child that failed once its parent has succeeded.

The filter contains no environment-specific values that need replacing before go-live.

Description: This mapping collection writes an iPaaS.com Product Category into commercetools as a product category, creating it on first transfer and updating it thereafter, with its parent reference carried so the taxonomy hierarchy is reproduced.

Mapping Type	Source Field (iPaaS.com)	Destination Field (commercetools)	Description
Field	Name	description_enUS	Required in practice. Writes the iPaaS.com category name into the English description. commercetools does not require a description, but the update path reads this value to compare it against the value already stored, so a category updated with no description value fails. Note that the shipped default reads the category name, not a description field — see the paragraph below the table.
Dynamic Formula	Category-path derivation, reproduced after this table	Key	Recommended. Builds the commercetools category key from the category name prefixed by its full subcategory trail, with separators and spaces replaced by underscores, repeated underscores collapsed, and every remaining character that is not a letter, digit, hyphen or underscore stripped. Including the trail is what keeps the key unique when two branches hold categories of the same name. commercetools does not require a key, but this collection writes one on every transfer and it serves as the stable, human-readable handle for the category. Leave it mapped.
Field	Name	Name	Required. Writes the iPaaS.com category name into the English name of the commercetools category — the label shoppers and merchandisers see. The commercetools HTTP API specification for category records (retrieved 2026-07-20) lists name as a required property on a new category, and a transfer with no name value is rejected.
Dynamic Formula	`return await GetExternalIdAsync(ParentId, "Product Category", SpaceportSystemId);`	parent_id	Optional, and applies only to child categories. Resolves the iPaaS.com parent category to the commercetools identifier that iPaaS.com stored when that parent was transferred, and writes it as the parent reference. A top-level category has no parent, the lookup returns no value, and the category is correctly written as a root-level category. This mapping resolves a link that must already exist — it does not create one.
Dynamic Formula	Category-path derivation, reproduced after this table	slug_en	Required. Builds the URL-facing category slug using the same derivation as Key. The commercetools HTTP API specification for category records (retrieved 2026-07-20) lists slug as a required property on a new category; in addition this integration reads and reformats the slug value on every write, so a category transferred with no slug value fails rather than transferring without one. commercetools also treats the slug as unique within a project.

The Key and slug_en mappings both use the following derivation. It is reproduced here verbatim because it is multi-line and cannot be shown inside a table cell:

var result = Name;
if (SubcategoryTrail != null)
result = SubcategoryTrail + " > " + Name;
result = result.Replace(">","_");
result = result.Replace(" ","_");
result = result.Replace("___","_");
result = result.Replace("__","_");
Regex rgx = new Regex("[^a-zA-Z0-9-_]");
return rgx.Replace(result, "");

The formula starts with the category Name. Where SubcategoryTrail carries a value — that is, where the category sits beneath other categories — it prefixes the full trail so the result reflects the whole path rather than the name alone. It then replaces the trail separator and spaces with underscores, collapses runs of repeated underscores down to a single one, and finally strips every remaining character outside the letters, digits, hyphen and underscore that commercetools accepts. If the category name is empty, the derived value is empty and the transfer is rejected by commercetools. The formula handles the character set but not the length limit — see commercetools Caveats.

The description is sourced from the category name. The shipped default mapping for description_enUS reads Name, the same source as the Name mapping. This is deliberate — it guarantees the description value that the update path requires is always present — but it means every transferred category arrives in commercetools with its name repeated as its English description, and a description maintained separately in iPaaS.com is never transferred. Subscribers who maintain genuine category descriptions should repoint this mapping at that field before the first production transfer, and ensure the chosen field is populated on every category.

Error Handling

The full catalogue of user-facing messages for this integration is in the commercetools Error Messages article. The messages most often seen on this collection are:

"Parent category must be uploaded first" — Raised by this collection's mapping filter when a child category is transferred before its parent has been transferred to commercetools. The category is not written. Resolution: transfer the parent category first, confirm it succeeded, then re-run the child with Manual Sync. Work down the taxonomy from the root when transferring in bulk. The integration will not transfer the parent or retry the child on its own.
A rejected category key or slug — commercetools rejects the write when the derived key or slug exceeds its length limit or duplicates the slug of an existing category. Resolution: shorten the category name or reduce the nesting depth, or adjust the Key and slug_en derivation mappings. For a duplicate slug, rename one of the two colliding categories so the derivations diverge.
A missing required value — commercetools rejects a category with no name or no slug, and this collection fails on update when the description value is empty. Resolution: populate the category name in iPaaS.com, which supplies the name, description, key and slug under the default mappings, and re-run the transfer.
A failure on a very short category name — a category whose name is shorter than three characters can fail on update because of how the update path derives its internal comparison value. Resolution: lengthen the category name, or validate short names in a staging environment before relying on them in production.
An out-of-date record version — the write is rejected when the commercetools category was edited elsewhere between the integration's version read and its write. Resolution: re-run the transfer with Manual Sync.
An authorization failure on the first transfer — the connection test reports success without contacting commercetools, so a credential or configuration problem surfaces here instead. Resolution: correct the settings per Connections and Settings and re-run a single Manual Sync.

All of these appear in Dashboard / Integration Monitoring / Error Logs, where the message text can be searched directly. Nothing is retried automatically.

Validation Rules

Parent presence. A category with a parent is transferred only when that parent already carries a commercetools link. Enforced by the mapping filter, before any write, by rejection.
Name present. A category must carry a name. Enforced by commercetools, which lists name as required on a new category, and in practice by the derivations that read it.
Slug present and unique. A category must carry a slug, and the slug must be unique within the commercetools project. Enforced by commercetools on write.
Description present. Enforced by the integration on the update path, which reads the incoming description in order to compare it. An empty value fails.
Key and slug character set. Restricted to letters, digits, hyphens and underscores. Enforced by the derivation formula.
Key and slug length. Enforced by commercetools on write. Not enforced by the derivation formula, which is why long names and deep trees need validating before production use.
Record version currency. Enforced by commercetools on every update.

Testing & Validation

Test Scenarios

Transfer a top-level category. Create a root-level Product Category in iPaaS.com and transfer it with Manual Sync. Expected: the category appears in commercetools with no parent, and the iPaaS.com record carries a commercetools external-ID link.
Transfer a child category after its parent. With the parent already transferred, transfer a child category. Expected: the category appears in commercetools beneath its parent, and its derived key and slug include the parent trail.
Transfer a child category before its parent. Transfer a child whose parent has never been transferred. Expected: the transfer fails with Parent category must be uploaded first in Dashboard / Integration Monitoring / Error Logs, and no category is created in commercetools. Then transfer the parent, re-run the child, and confirm it succeeds.
Update an existing category. Change the name of a category already linked to commercetools and re-transfer. Expected: the commercetools category is updated rather than duplicated, and the name, description, key and slug all reflect the change.
Confirm no field is cleared on update. Re-transfer a category with no changes. Expected: the transfer succeeds and no category values change, because matching values are compared and dropped before the write.
Verify the description behavior. Inspect a transferred category in commercetools. Expected under the shipped defaults: the English description equals the category name. If the description mapping has been repointed, confirm it carries the intended field instead.
Verify the Manual Sync ID format. Transfer a category by entering its iPaaS.com Product Category identifier. Expected: the record resolves and transfers. A commercetools GUID entered here will not resolve.
Test a long or deeply nested category name. Transfer a category whose derived key and slug are long. Expected: either a successful transfer, or a commercetools rejection identifying the length constraint — establishing where the taxonomy's practical limit sits before production.
Test a slug collision. Transfer two identically named categories sitting in identically named branches. Expected: the second write is rejected on slug uniqueness.
Test a category name shorter than three characters. Transfer it, then update it. Expected: the update path may fail; confirm the behavior before allowing short names in production data.

Validation Checklist

The commercetools connection settings have been confirmed by a successful Manual Sync, not by the connection test.
Every iPaaS.com Product Category intended for transfer carries a name.
The description mapping has been reviewed, and repointed if genuine category descriptions are maintained upstream.
The taxonomy transfer order has been planned from the root downward.
Derived key and slug values have been checked against the commercetools length constraint for the longest names and the deepest branches in the taxonomy.
The category/product/created and category/product/updated subscriptions are enabled under Outbound Data Flows where the automatic path is required.
The category taxonomy is transferred before the product catalogue is published.
Dashboard / Integration Monitoring / Error Logs has been checked after the first bulk transfer and any rejected records have been re-run.
The project's commercetools category quota has been confirmed where the taxonomy approaches 10,000 categories.

Additional Notes

At the time this documentation was written, the following are outside the scope of this collection:

Category delete — not performed by this integration in any direction. Deletions must be made directly in commercetools.
Inbound category transfer — there is no flow that brings commercetools categories into iPaaS.com. This collection is outbound only.
Product-to-category assignment — attaching products to categories is performed by the Product collection, not by this one.
Category assets, meta titles, meta descriptions and meta keywords — these commercetools category properties are not written by this collection.
Collision handling and duplicate detection — not implemented for any collection in this integration.
Initialization — bulk initialization of existing commercetools categories is not supported.
Automatic dependency transfer — the parent-ordering requirement on this collection is enforced by rejection, not resolved by transferring the parent automatically.

The endpoints this integration calls are listed in API Endpoints. Integration-wide constraints, including the region constraint that applies to this collection along with every other, are described in the commercetools Integration Known Limitations article. The full message catalogue is in the commercetools Error Messages article.

For assistance, contact iPaaS.com Support at support@ipaas.com.

iPaaS.com to commercetools Category Mapping Documentation