Overview
This article catalogs the error messages the Zoho Commerce integration can raise during data synchronization, grouped by the mapping collection flow that produces them. Each entry gives the message a subscriber sees, what causes it, whether the wording can be changed, and the steps that resolve it. Errors raised by this integration appear under Dashboard / Integration Monitoring / Error Logs.
Not every unexpected outcome is an error. Behavior such as a category assignment that finds no match and is skipped without a message, a tax-free order producing no tax record, or a variant field that is mapped but not carried on a direct variant write, is documented in the Zoho Commerce Known Limitations article and in the mapping documentation for the affected entity — the Category, Product, Inventory and Sales Order mapping documentation articles. Those cases produce no error entry, so a transfer that appears to have succeeded but did not carry the data you expected should be researched there rather than here.
A small number of failures reach the Error Logs without descriptive text — most commonly when Zoho Commerce answers a read with an empty or unreadable body. Where the log entry carries no message you can act on, contact iPaaS.com Support at support@ipaas.com with the timestamp of the entry and the record being transferred.
Supported Flows
Connection and Authorization
All Mapping Collection Flows
Add/Update Zoho Commerce Category FROM iPaaS.com
Add/Update Zoho Commerce Product Inventory FROM iPaaS.com
Add/Update Zoho Commerce Product Variant Inventory FROM iPaaS.com
Add/Update Zoho Commerce Sales Order Unmapped Payment TO iPaaS.com
Error Collection
Connection and Authorization
These errors are raised while the subscription is being connected to a Zoho Commerce store, not during a record transfer. They appear when the Authorize step is run from the subscription.
Client ID missing during authorization
Error message: Unable to complete OAuth process in ProcessAuthorization. ClientId is not specified in the CustomFields for this SystemTypeVersion
Description: The Authorize step ran without a client identifier available to exchange for a token, so authorization stopped before Zoho Commerce was contacted. Despite the wording, the value the integration looks for is the Client_Id connection setting on the subscription, not a value held anywhere else. The message names the wrong place to look, so treat the Client_Id setting as the field to check.
Error source: Raised by the integration. The wording cannot be changed by subscribers or their MiSP.
Resolution: Open the subscription's connection settings and confirm Client_Id is populated with the client identifier from the Zoho API console entry you created for this store, with no leading or trailing spaces. Save the settings and run Authorize again. Field-by-field guidance is in the Zoho Commerce Connections and Settings article and the Zoho Commerce Installation Instructions article. If the setting is populated and the error persists, contact iPaaS.com Support at support@ipaas.com with the timestamp of the error entry.
Client Secret missing during authorization
Error message: Unable to complete OAuth process in ProcessAuthorization. ClientSecret is not specified in the CustomFields for this SystemTypeVersion
Description: The Authorize step ran without a client secret available to exchange for a token. As with the message above, the value the integration looks for is the Client_Secret connection setting on the subscription, so that is the field to check rather than the location the message names.
Error source: Raised by the integration. The wording cannot be changed by subscribers or their MiSP.
Resolution: Open the subscription's connection settings and confirm Client_Secret is populated with the secret issued alongside the client identifier, copied whole and without surrounding spaces. Save the settings and run Authorize again. If the setting is populated and the error persists, contact iPaaS.com Support at support@ipaas.com with the timestamp of the error entry.
Authorization code could not be exchanged for a token
Error message: Unable to complete OAuth process in ProcessAuthorization. Failed to convert temporary code into a permanent token
Description: The Authorize step reached Zoho, but Zoho did not return a usable access token in exchange for the temporary authorization code. The usual causes are an authorization code that has already been used or has expired because too long passed between granting access and the exchange completing, a redirect address on the Zoho API console entry that does not match the one the authorization was started from, or a Zoho account provisioned outside the United States data center. Authentication is tied to the United States Zoho data center, so a store whose Zoho organization lives in another region cannot complete this step at all.
Error source: Raised by the integration. The wording cannot be changed by subscribers or their MiSP.
Resolution: Run the Authorize step again from the beginning and complete the Zoho consent screen promptly rather than leaving it open, so the code is exchanged while it is still valid. Confirm the redirect address recorded on your Zoho API console entry matches the one used by the authorization flow, as described in the Zoho Commerce Installation Instructions article. Confirm with your Zoho administrator that the organization is provisioned in the United States data center. If all three are correct and the exchange still fails, contact iPaaS.com Support at support@ipaas.com with the timestamp of the error entry.
All Mapping Collection Flows
These two errors can be raised by any mapping collection, in either direction, because every transfer makes at least one call to Zoho Commerce.
Zoho Commerce rejected the request
Error message: the entry opens with a fixed prefix naming the integration and the operation being performed, continues with the response Zoho Commerce returned — normally a numeric code and a short explanation — and closes with the HTTP status code in parentheses.
Description: Zoho Commerce answered the call with a status other than success and the transfer stopped. This is the most common error the integration raises, and it covers everything Zoho Commerce itself objects to: a required field left empty, a value that fails a Zoho Commerce validation rule, a storefront URL that duplicates one already in use, a stock cost of zero or below on a product update, an expired or revoked token, a missing or incorrect Organization ID, or a request the store refused because calls were made too quickly. Zoho does not publish a call quota for the Zoho Commerce store API, and a store may still refuse calls made too quickly. The response Zoho Commerce returned is passed through exactly as Zoho Commerce wrote it, so the portion after the prefix is the authoritative explanation and is the part to read first. It is unformatted, and the leading prefix identifies the operation internally rather than in storefront terms, so read past it to the Zoho Commerce text.
Error source: Raised by the integration around the response Zoho Commerce returned. Neither the prefix nor the Zoho Commerce text can be changed by subscribers or their MiSP.
Resolution: Read the Zoho Commerce portion of the message and correct the condition it names. In order: (1) correct the record in the source system or the mapping that supplies the field Zoho Commerce objected to, then re-transfer the record through Manual Sync; (2) if the message indicates the request was not authorized, confirm Organization_Id is populated in the subscription's connection settings and run the Authorize step again, since a green connection test does not confirm that credentials are valid; (3) if the message indicates the store is refusing calls made too quickly, wait and re-transfer, and stagger large runs rather than sending everything at once. Where the Zoho Commerce text does not identify a field you can correct, contact iPaaS.com Support at support@ipaas.com with the full message text, the timestamp, and the record identifier.
Zoho Commerce could not be reached
Error message: the network-level failure reported by the connection attempt, passed through unchanged — for example a host that could not be resolved, a connection that timed out, or a secure connection that could not be established.
Description: The call did not reach Zoho Commerce at all, so no response was received to interpret. This is raised for transport-level failures rather than for anything Zoho Commerce decided: an unreachable or mistyped store address in the API Url connection setting, a Zoho Commerce outage, or a network interruption between iPaaS.com and Zoho.
Error source: Raised by the integration around the failure the connection attempt reported. The wording cannot be changed by subscribers or their MiSP.
Resolution: Confirm the API Url setting on the subscription matches the store address documented in the Zoho Commerce Connections and Settings article. Confirm the Zoho Commerce store is reachable in a browser. Re-transfer the affected records through Manual Sync once the store responds, since a transfer stopped this way did not reach Zoho Commerce and nothing was written. If the setting is correct, the store is reachable, and the failure repeats, contact iPaaS.com Support at support@ipaas.com with the timestamp of the error entry.
Add/Update Zoho Commerce Category FROM iPaaS.com
Parent category has not transferred yet
Error message: Parent category must be uploaded first
Description: A nested category was transferred before the category above it in the hierarchy had reached Zoho Commerce. The collection's mapping filter checks, for any category that has a parent, whether that parent already has a Zoho Commerce link recorded against it. Where it does not, the transfer is stopped with this message rather than creating a category in the wrong place in the storefront hierarchy. Top-level categories carry no parent and always process. This is ordering, not a defect in the record: it typically clears on its own once the parent category transfers and the child record is transferred again.
Error source: Raised by this collection's mapping filter. Subscribers or their MiSP can change the wording, or the condition itself, by editing the filter on Add/Update Zoho Commerce Category FROM iPaaS.com in the iPaaS.com mapping page and redeploying.
Resolution: (1) Transfer the parent category first, either by letting the outbound triggers work through the hierarchy from the top down or by transferring the parent through Manual Sync. (2) Transfer the child category again — it will succeed once the parent link exists. (3) When loading a category tree for the first time, transfer categories in hierarchy order, parents before children, so the condition is not met at all. If the parent has demonstrably transferred and is linked but the child still stops, contact iPaaS.com Support at support@ipaas.com with the timestamp and both category record identifiers.
Add/Update Zoho Commerce Product Inventory FROM iPaaS.com
Variant reference missing on an inventory record
Error message: Variant id is required
Description: The inventory record reached the transfer without a usable reference to the Zoho Commerce stocking unit whose level is being adjusted. Zoho Commerce holds stock against a variant rather than against the product record, so the integration needs both the variant reference and the location reference before it can calculate an adjustment. The reference is missing when the product the inventory belongs to has not yet transferred to Zoho Commerce, so no variant link exists to adjust against. The wording can read as though the feature is unavailable; it is not. It means a required value is missing.
Error source: Raised by the integration. The wording cannot be changed by subscribers or their MiSP.
Resolution: (1) Confirm the product that owns this stock level has already transferred successfully through Add/Update Zoho Commerce Product FROM iPaaS.com, since the variant link is recorded as part of that transfer. (2) Transfer the product again if it has not, then re-transfer the inventory record through Manual Sync. (3) Confirm the inventory record identifies both the stocking unit and the location, and that the location exists in Zoho Commerce. If the product is linked, the location exists, and the message repeats, contact iPaaS.com Support at support@ipaas.com with the timestamp and the inventory record identifier.
Stored inventory link is not in the expected form
Error message: Invalid data passed to <ClassName>.SetPrimaryKey.<FieldName>: <PrimaryId>
Description: The message names the internal object and field the integration was writing the link back to, and closes with the value it was given. It is raised when the stored inventory link is not the expected two-part variant-and-location value — Zoho Commerce identifies a stock level by the combination of the stocking unit and the location it is held at, and the integration records that pairing as the external identifier for the inventory record. A value that carries only one part, carries more than two, or was edited by hand into another shape cannot be split back into a variant and a location, and the transfer stops here. This is a different condition from Variant id is required above: that message means no variant reference was supplied at all, while this one means a reference was supplied in a form the integration cannot read.
Error source: Raised by the integration. The wording cannot be changed by subscribers or their MiSP.
Resolution: (1) Compare the external identifier recorded against the inventory record with the format documented for this collection in the iPaaS.com to Zoho Commerce Inventory Mapping Documentation article — it must carry the stocking unit and the location as a single two-part value. (2) Where the identifier was set or edited outside the integration, clear it so the next transfer records it again, then re-transfer the inventory record through Manual Sync. (3) Confirm the product that owns the stock level has transferred successfully, since the identifier is written as part of the inventory transfer that follows it. If the identifier matches the documented format and the message repeats, contact iPaaS.com Support at support@ipaas.com with the timestamp, the inventory record identifier and the full message text.
Add/Update Zoho Commerce Product Variant Inventory FROM iPaaS.com
Variant reference missing on an inventory record
This collection raises the same Variant id is required message, for the same reason and with the same resolution, when the variant whose stock is being adjusted has not yet transferred to Zoho Commerce. See Variant reference missing on an inventory record under Add/Update Zoho Commerce Product Inventory FROM iPaaS.com above, substituting the variant and its parent product for the product.
Stored inventory link is not in the expected form
This collection raises the same Invalid data passed to <ClassName>.SetPrimaryKey.<FieldName>: <PrimaryId> message, for the same reason and with the same resolution, when the stored link for the variant's stock level is not the expected two-part variant-and-location value. See Stored inventory link is not in the expected form under Add/Update Zoho Commerce Product Inventory FROM iPaaS.com above.
Add/Update Zoho Commerce Sales Order Unmapped Payment TO iPaaS.com
Order paid with an unlisted payment method
Error message: this collection stops the order without adding message text of its own. The entry in the Error Logs identifies the order that was stopped and names Add/Update Zoho Commerce Sales Order Unmapped Payment TO iPaaS.com as the collection that stopped it.
Description: This collection holds the list of payment methods you have accounted for in your mappings, and it exists to stop orders rather than to capture anything. An order whose payment method appears on the list passes through untouched and is captured normally. An order whose payment method is not on the list is stopped here and raised as an error, so that the order does not land in iPaaS.com as a partial record needing manual repair. The comparison is against the payment method name exactly as Zoho Commerce records it on the order, so a difference in spelling or capitalization is treated as an unlisted method. As delivered, the list names only a test gateway and a placeholder entry, so every order paid with a real payment method is stopped until the list is replaced. It is also raised when a new payment method is introduced or renamed in the storefront without being added to the list.
Error source: Raised by this collection's error condition. Subscribers or their MiSP change the behavior by editing the payment method list on Add/Update Zoho Commerce Sales Order Unmapped Payment TO iPaaS.com in the iPaaS.com mapping page and redeploying.
Resolution: (1) Open the collection in the iPaaS.com mapping page and replace the delivered list with every payment method your storefront accepts, spelled exactly as Zoho Commerce records it on an order. Confirm the exact values against a real order in a staging environment before relying on them. (2) Add the same entry to the collection's error condition so the two stay in step. (3) Redeploy, then re-transfer the stopped orders through Manual Sync — they are captured successfully once their payment method is listed. (4) Repeat step 1 whenever a payment method is added or renamed in Zoho Commerce. If an order is stopped even though its payment method is on the list and spelled identically, contact iPaaS.com Support at support@ipaas.com with the timestamp and the order identifier.