A passing connection test is not evidence that your credentials work. At the time this documentation was written, the connection test reports success regardless of whether the credentials are valid, so a wrong or expired credential does not surface when you test the connection — it surfaces on the first real transfer, as CTLS-EXTN-1002 with an HTTP status of Unauthorized.

Some failures come from iPaaS.com rather than from commercetools. When the integration looks up an iPaaS.com record during a transfer — this is how categories, locations, tax categories, and product types are resolved — a failed lookup surfaces as an iPaaS.com platform error carrying a two-segment platform code, not a CTLS code. The usual cause is that the referenced record has not been transferred to commercetools yet, so no link between the two systems exists. Transfer the referenced record first, then re-run the failed transfer.

Connection and Authentication

All Data Transfer Flows

Product FROM iPaaS.com

Product Variant FROM iPaaS.com

Product Category FROM iPaaS.com

Product Inventory FROM iPaaS.com

Description: The integration attempted to obtain an access token from commercetools and found no client ID value. This occurs when the connection is first established, and again whenever a stored token has to be replaced. The value is read from the Client_Id subscription setting described in Connections and Settings; that setting is the only place to look.

Resolution: Open your subscription's settings and confirm that Client_Id is present and has no leading or trailing spaces. The value comes from the API Client you created in the commercetools Merchant Center. If you no longer have it, create a new API Client and re-enter all four connection values, as listed in Connections and Settings.

Description: The same authorization step found no client secret value. It is read from the Client_Secret subscription setting. commercetools displays a client secret only once, at the moment an API Client is created, so this error most often means the secret was never captured or was pasted incompletely.

Resolution: Confirm that Client_Secret is populated in your subscription settings. Because commercetools does not display an existing secret a second time, you cannot recover the original value — create a new API Client in the Merchant Center and re-enter Client_Id, Client_Secret, Scope, and API Url together, as described in Connections and Settings.

Description: The integration sent your credentials to the commercetools authorization service and did not get a usable access token back. The usual causes are an incorrect Client_Secret, a Scope value that does not match the project key in your API Url, an API Client that has been deleted or has expired in the Merchant Center, or a commercetools project hosted outside the region this release supports. Region support is covered in API Endpoints and in Known Limitations.

Resolution: Check, in order: that Scope contains the same project key that appears in API Url; that the API Client still exists and is active in the commercetools Merchant Center; and that the scopes granted to that API Client cover the collections you are transferring. Re-entering Client_Secret from a freshly created API Client resolves most occurrences. Confirm your project's region is supported before troubleshooting further — see API Endpoints.

Description: commercetools returned a non-success HTTP status for a create, update, or read. This is the most common error in the integration and is a wrapper around whatever commercetools itself reported. {action} names the operation in subscriber-facing terms, {details} carries the error text commercetools returned — including its own error code and message where it supplies them — and {status} is the HTTP status name. What the status usually means:

Unauthorized: the credentials or the granted scopes do not permit the operation. Because the connection test always reports success, this is where an invalid credential first appears.

BadRequest: the record failed commercetools validation: a required field missing, a value outside an allowed set, or a reference to a record that does not exist in your project. On the Product Category flow the most frequent causes are an empty or unmapped name, description, or slug, and a key or slug that duplicates one already in the project — commercetools requires both to be unique, and reports each clash separately as DuplicateField, naming the field and the identifier of the record already holding the value. On the inventory flows the most frequent cause is a supply channel that does not exist in your project.

Conflict: another process changed the same record between the moment the integration read it and the moment it wrote it back.

NotFound on an update: the destination record no longer exists.

TooManyRequests: you exceeded the request rate your project allows.

Resolution: Read the {details} portion of the Error Logs entry first — commercetools names the offending field in its own error text. Correct the source record or the mapping that produces that field, then re-run the transfer. When the detail reports DuplicateField, the record already exists in commercetools but is not linked to the iPaaS.com record being transferred — most often because it was created directly in the Merchant Center, or by an earlier transfer whose link was lost. This integration does not merge or re-link a record it did not create, so re-running will keep failing until one of two things happens: change the duplicated value on the source record, or ask your MiSP to link the existing commercetools record to the iPaaS.com record so subsequent transfers update it instead of creating a new one. For a Conflict, simply re-run; the integration reads the current record version each time it writes, so a retry normally succeeds once the competing change has settled. For TooManyRequests, transfers are not automatically rescheduled or resumed by this integration — stagger large jobs, avoid running several intensive transfers at the same time, and re-run the affected records; commercetools publishes its request limits at https://docs.commercetools.com/api/limits. For Unauthorized, re-verify Client_Id, Client_Secret, Scope, and API Url against the API Client in your Merchant Center, and confirm the granted scopes cover the resource being written — for example manage_products for a product transfer. If the details name no field, ask your MiSP to review the mapping that produced the record.

Description: The request never reached commercetools, or the response could not be read. This covers name resolution failures, TLS or certificate negotiation failures, and connection timeouts. {action} names the operation in subscriber-facing terms and {details} carries the underlying network or certificate message, which is the text that names the actual cause.

Resolution: Confirm that the host in your API Url setting is reachable and spelled correctly, including its region component — see Connections and Settings and API Endpoints. Re-run the transfer, since transient network failures do not repeat. If the failure is consistent, or the details name a certificate or TLS problem, contact your MiSP, or iPaaS.com Support at support@ipaas.com.

Description: A delete was requested for a commercetools record. Delete is not supported by this integration for any entity, in either direction. {entity} names the record type that was being deleted.

Resolution: Remove any configuration that asks the integration to delete a commercetools record, including delete-triggered outbound data flows. Records must be removed directly in the commercetools Merchant Center. See Known Limitations for the full statement of what is and is not supported. If no delete is configured anywhere in your subscription, ask your MiSP to review your data flow triggers.

Description: A create, read, or update was requested on a record type that supports only the opposite direction. Orders, order lines, and payments transfer from commercetools into iPaaS.com and are not written back; product variants are read through their parent product rather than on their own. {operation} names the operation attempted and {entity} names the record type.

Resolution: Check the direction configured on the mapping collection named in the Activity Tracker entry against the directions the integration supports, listed in Known Limitations. Disable the collection or correct its direction. If you expected this record type to transfer in this direction, ask your MiSP to confirm the intended design of your data flows.

Description: A transfer was configured for a record type this integration does not implement. The integration supports a defined set of collections — customer, customer address, order and its child collections, product, product variant, product attribute, product category, product inventory, and location. A collection outside that set produces this error as soon as a transfer is attempted.

Resolution: Disable or remove the mapping collection named in the message. Consult Known Limitations for the definitive list of supported collections before configuring new transfers. If the collection named is one you expected to be supported, ask your MiSP to confirm which collections your subscription is configured for.

Description: The integration asked commercetools for a record and received nothing back. {entity} names the record type. The usual cause is that the record was deleted in the commercetools Merchant Center after it was linked to iPaaS.com, so the stored link now points at a record that no longer exists. It can also occur when a record is looked up by a key that does not match any record in your project. One case is worth calling out separately: when {entity} is tax category, the lookup came from the tax-class mapping function rather than from a record link, and it means your project returned no tax categories at all.

Resolution: Confirm in the commercetools Merchant Center that the record still exists. If it was deleted deliberately, ask your MiSP to clear the stored link between the two systems so the next transfer creates a new record rather than trying to update a missing one. If the record does exist, check that the value the mapping uses to identify it matches the record's key in commercetools. For the tax category case, confirm that tax categories are defined in your commercetools project and that the API Client's granted scopes allow reading them — a mapping that converts a tax class name cannot resolve anything until at least one tax category exists.

Description: The transfer reached the point of writing to commercetools but the record to be written had not been built. This normally means the mapping produced no usable record — for example, every mapped field evaluated to empty, or a Dynamic Formula returned nothing. {collection} names the mapping collection involved.

Resolution: Open the mapping collection named in the message and confirm that its required fields are mapped and that the source records actually carry values for them. Test any Dynamic Formula in the mapping to confirm it returns a value for the record that failed. If the mapping is complete and populated source records still produce this error, contact your MiSP, or iPaaS.com Support at support@ipaas.com with the Error Logs entry.

Description: The record handed to the integration was not the type the named collection expects. This normally indicates a mapping collection configured against the wrong record type, or a child collection linked to the wrong parent.

Resolution: Review the mapping collection named in the message and confirm it is configured for the intended record type, and that any child collection is attached to the correct parent collection. If the configuration is correct, contact your MiSP, or iPaaS.com Support at support@ipaas.com with the Error Logs entry.

Description: A product could not be written to commercetools because no product type was resolved for it. Every commercetools product must reference a product type, and this integration does not create one for you. It occurs on both creates and updates. The shipped default mapping resolves the product type through a Lookup Translation whose destination values are product type identifiers specific to your commercetools project — those shipped values are examples and must be replaced with your own before go-live. If the Lookup Translation has no entry matching the source product's category, or the entry still holds an example identifier that does not exist in your project, no product type is resolved and this error is raised.

Resolution: Open the Lookup Translation used by the productType_id mapping on this collection and confirm it has an entry for the source value on the failing product, and that the destination value is a product type identifier that genuinely exists in your commercetools project. Product type identifiers can be read from the commercetools Merchant Center. The placeholder values shipped with the default mappings are listed in Known Limitations — replace all of them before running production transfers. Once the Lookup Translation is corrected, re-run the transfer.

Description: A new variant was being added to a product and carried no attribute values. commercetools distinguishes variants of the same product by their attribute values, so a variant with none cannot be created. This applies only to variants being created; existing variants being updated are unaffected.

Resolution: Open the Product Variant FROM iPaaS.com mapping collection and confirm that at least one attribute is mapped and that the source variant carries a value for it. Variants that legitimately have no distinguishing attributes should not be transferred as separate variants. Re-run the transfer once the source data or the mapping is corrected.

Description: The product being transferred has more than 100 variants, and the transfer was stopped before any data was sent. commercetools documents a 100-variant limit per product but states that the limit can be increased per project after they review the performance impact (see https://docs.commercetools.com/api/limits), so it is configurable rather than a fixed platform restriction. The integration's own check is fixed at 100 and does not read your project's actual limit, so a product is blocked here even if commercetools has already raised the limit for your project. Treat the number in this message as the integration's threshold, not as your project's.

Resolution: This check is an error filter on the Product FROM iPaaS.com mapping collection, which means it is a Dynamic Formula you or your MiSP can edit in the iPaaS.com user interface. If commercetools has confirmed a higher variant limit for your project, edit the error filter on this collection to match the limit your project actually has. If your project is on the standard 100-variant limit, either reduce the number of variants on the source product or split it into more than one product before re-running the transfer. Request a limit increase from commercetools only after confirming your project has not already been granted one.

Description: commercetools accepted the product call but returned a response the integration could not use to finish the transfer — most often a response body that omitted the product data needed to link the record back to iPaaS.com. The product may exist in commercetools without being linked to iPaaS.com.

Resolution: Check whether the product was in fact created or updated in the commercetools Merchant Center. If it was, re-run the transfer for that product so the link can be established; the integration matches on the identifier and will update rather than duplicate. If the same product fails repeatedly, or you find duplicates in commercetools, contact your MiSP, or iPaaS.com Support at support@ipaas.com with the Error Logs entry and the product involved.

Description: A product variant could not be created or updated because the parent product it belongs to was not identified. commercetools stores variants inside the product record, so the product must be known before a variant can be written. This normally means the parent product has not yet been transferred to commercetools, or the parent product transfer failed earlier in the same run and the variant was attempted anyway.

Resolution: Confirm the parent product transferred successfully to commercetools before the variant was attempted — check the Error Logs for a failure on the Product FROM iPaaS.com collection in the same run and resolve that first. Because the product must exist before any of its variants, transferring the product on its own and then re-running the variant transfer resolves most occurrences.

Description: A category that has a parent category was transferred before its parent existed in commercetools. This integration does not transfer a record's dependencies automatically, so categories must reach commercetools in hierarchy order — parents before children. The check compares the parent named on the incoming category against the categories already linked between the two systems; if no link is found, the transfer is stopped. Top-level categories with no parent are not affected.

Resolution: Transfer the parent category first, then re-run the failing category. For a first-time load of a full category tree, transfer the tree one level at a time from the top down. This check is a filter on the Product Category FROM iPaaS.com mapping collection and is a Dynamic Formula you or your MiSP can view and edit in the iPaaS.com user interface — but the underlying requirement is real, so removing the check will not make the transfer succeed; it will only replace this clear message with a rejection from commercetools.

Description: An inventory record could not be created because the product it applies to was not identified. This applies to all four inventory collections — Product Inventory, Product Variant Inventory, and both standalone inventory update collections. The usual cause is that the product or variant has not yet been transferred to commercetools, so no link exists to attach the inventory record to.

Resolution: Transfer the product and its variants to commercetools before transferring inventory. Check the Error Logs for a product or variant failure earlier in the same run and resolve that first, then re-run the inventory transfer. Also confirm that a location is mapped on the inventory collection — an inventory record created in commercetools without a supply channel cannot be updated by this integration afterwards, so location should be treated as required rather than optional on all four inventory collections. Confirm that MinQuantity is mapped as well: when it is left unmapped, newly created inventory records are written with an available quantity of zero, which reads as out of stock rather than as an error. See Known Limitations for the detail.

iPaaS.com <> Commercetools: Background

commercetools Installation Instructions

commercetools Connections and Settings

Commercetools Mapping Functions

commercetools API Endpoints

commercetools Known Limitations