Connection & Authentication

All Flows (external Shopify API errors)

Customer (TO / FROM iPaaS.com)

Customer Category (TO iPaaS.com)

Company / B2B (TO / FROM iPaaS.com)

Product, Variant & Inventory (FROM iPaaS.com)

Product Category & Collection (TO / FROM iPaaS.com)

Order (TO / FROM iPaaS.com)

Order Return (FROM / TO iPaaS.com)

Location (FROM iPaaS.com)

Webhook Subscription

Description: No usable authentication was found on the subscription — neither an API Password (permanent access token) nor a Client Id + Client Secret pair.

Resolution: Open the Shopify subscription settings and provide one authentication method: an API Password for a legacy private app, or a Client Id and Client Secret for a private app created after April 1, 2026 — or re-install the public app. See Shopify Connections and Settings.

Description: The subscription is missing one or more required connection settings, so the integration cannot reach Shopify.

Resolution: Confirm API Store, API Version, and the credentials for your authentication method are populated in the Shopify subscription settings. See Shopify Connections and Settings.

Description: An OAuth install was attempted but the Client Id and/or Client Secret were not provided in the subscription settings.

Resolution: Enter the app's Client Id and Client Secret in the Shopify subscription settings, then retry the installation.

Description: Shopify could not exchange the temporary authorization code for a permanent access token — usually an expired or already-used code, or a Client Id / Client Secret mismatch.

Resolution: Restart the app installation so a fresh authorization code is issued, and confirm the Client Id and Client Secret match the Shopify app. If it continues to fail, your MiSP can investigate.

Description: Shopify rejected the request as unauthorized — the access token or credentials are invalid or expired, or the app is missing a required access scope.

Resolution: Re-check the credentials in the subscription settings and confirm the Shopify app was installed with all required scopes (see Shopify Connections and Settings). Re-install or re-authorize the app if the token is no longer valid.

Description: A call from the integration to the Shopify API failed. The message includes the reason Shopify returned and the HTTP status code. Common causes include an invalid identifier or parameter, or Shopify otherwise rejecting the request.

Resolution: Review the reason and status code in the message and correct the indicated record or setting. If the cause is unclear, share the message with your MiSP, who can investigate and, if needed, involve iPaaS.com Support.

Description: Shopify throttled the connection because too many API calls were made in a short window. The integration backs off and retries automatically, but a large burst can still surface this. The message includes how many seconds until more calls are available.

Resolution: Usually transient — the transfer retries on its own. Avoid running multiple large manual syncs at once, and stagger bulk jobs. If it persists, your MiSP can review the volume and timing of your syncs.

Description: The integration called a Shopify GraphQL mutation but received no response payload, so it could not confirm the result.

Resolution: Re-sync the record. If it recurs, your MiSP can capture the request and investigate with iPaaS.com Support.

Description: Shopify returned one or more field-level errors for the create or update. The specific field messages Shopify returned are appended. This surface covers several flows — for example an invalid return reason value, a rejected location field, or a customer/company validation error.

Resolution: Read the appended field messages and correct the indicated values on the iPaaS.com record, then re-sync. For return-reason values, see Return reason is not a valid value under Order Return.

Description: One of the Shopify API calls in a batched operation failed and the batch was configured to stop on the first exception.

Resolution: Review the failing operation named in the message and the related record, then re-sync. If the cause is unclear, your MiSP can investigate.

Description: The Shopify write succeeded, but a follow-up internal tracking call failed afterward. The data change in Shopify is not affected.

Resolution: Usually transient — re-sync to clear it. If it persists, your MiSP can investigate with iPaaS.com Support.

Description: Shopify rejected the customer create or update; the appended message is the reason Shopify returned (for example an invalid email or phone format).

Resolution: Correct the indicated field on the iPaaS.com Customer and re-sync.

Description: The customer was written to Shopify successfully, but the follow-on step that assigns the customer to a company failed — in Shopify a customer can be a contact for only one company. The customer's Shopify id was saved to iPaaS.com, so this is a partial success.

Resolution: Confirm the customer is not already a contact of a different company in Shopify, then re-sync. Because the id was saved, the re-sync reconciles against the existing customer rather than creating a duplicate.

Description: An order references a customer that does not yet exist in the destination, and the automatic customer prerequisite transfer failed — so the order cannot proceed.

Resolution: Resolve the underlying customer error (it appears separately in the logs) and re-sync the order. Confirm the Customer mapping is configured correctly.

Description: The integration tried to link an incoming customer to an existing iPaaS.com Customer by email address and could not.

Resolution: Confirm the customer's email is valid and that a matching Customer exists in iPaaS.com, then re-sync.

Description: While transferring an order, the integration could not link the order's customer to an existing iPaaS.com Customer by email, so the order cannot proceed.

Resolution: Confirm the customer email on the order is valid and that the customer exists in iPaaS.com, then re-sync the order.

Description: The integration linked the order's customer by email but could not then transfer that customer (one variant also could not remove the temporary link), so the order fails.

Resolution: Resolve the underlying customer error (logged separately), confirm the customer record is healthy in both systems, then re-sync the order.

Description: The integration tried to link an incoming customer to an existing iPaaS.com Customer by name and external id and could not save the link, which risks a duplicate. This is a warning — the transfer continues.

Resolution: Check whether a matching customer already exists in iPaaS.com. If a duplicate appears, your MiSP can help reconcile the records.

Description: A customer references a customer category (represented in Shopify as a customer tag) that could not be created as a prerequisite, so the customer transfer fails.

Resolution: Resolve the underlying customer-category error (logged separately) and re-sync the customer.

Description: The integration could not link an incoming Shopify customer tag to an existing iPaaS.com customer category by name.

Resolution: Confirm a matching customer category exists in iPaaS.com with the same name, then re-sync.

Description: Shopify rejected the B2B company create or update; the appended message is the reason Shopify returned. B2B must be enabled on the store.

Resolution: Confirm B2B is enabled and the company Name is valid, then re-sync. See Shopify Known Limitations.

Description: The company was written to Shopify successfully, but assigning the customer as its contact failed — in Shopify a customer can be a contact for only one company. The company's Shopify id was saved to iPaaS.com, so this is a partial success.

Resolution: Confirm the customer is not already a contact of a different company in Shopify, then re-sync. Because the id was saved, the re-sync reconciles against the existing company rather than creating a duplicate.

Description: A company depends on a related customer that could not be transferred as a prerequisite, so the company transfer fails.

Resolution: Resolve the related customer error (logged separately) and re-sync. Confirm the Customer mapping is configured correctly.

Description: A customer depends on a related company that could not be transferred as a prerequisite, so the customer transfer fails.

Resolution: Resolve the related company error (logged separately) and re-sync. Confirm the Company mapping is configured correctly.

Description: The integration tried to link an incoming company to an existing record by name and external id and could not save the link, which risks a duplicate. This is a warning — the transfer continues.

Resolution: Check whether a matching company already exists. If a duplicate appears, your MiSP can help reconcile the records.

Description: The integration could not link an incoming company to an existing iPaaS.com Company by its id.

Resolution: Confirm the company exists in iPaaS.com and that the id is consistent between systems, then re-sync.

Description: The product transfer to Shopify failed; the detailed reason is in the transfer's technical logs.

Resolution: Open the transfer's logs for the specific Shopify error, correct the indicated data on the iPaaS.com Product, and re-sync.

Description: The product update to Shopify failed; the detailed reason is in the transfer's technical logs.

Resolution: Open the transfer's logs for the specific Shopify error, correct the indicated data on the iPaaS.com Product, and re-sync.

Description: Shopify requires every variant to define at least one option value. A variant was sent with no option, so the product cannot be created.

Resolution: Ensure each variant on the iPaaS.com Product has at least one option value (for example Size or Color), then re-sync.

Description: A variant was sent without any of the required option values (Option1 / Option2 / Option3), so the product cannot be uploaded.

Resolution: Ensure each variant supplies at least one of Option1, Option2, or Option3, then re-sync.

Description: The product has more variants than the store's Shopify plan allows.

Resolution: Reduce the number of variants on the product, or upgrade the Shopify plan's variant limit, then re-sync.

Description: The product collection's collision matching is configured to match on a field the integration does not support for products.

Resolution: Product collision matching is supported by SKU. Confirm the collection's collision configuration and match on SKU.

Description: A product variant could not be created or updated in Shopify; the appended detail is the reason returned. A common cause is Shopify's bulk variant operation not returning an id for the variant.

Resolution: Review the appended detail, correct the indicated variant data on the iPaaS.com product, and re-sync. If it recurs, your MiSP can capture the Shopify response and investigate.

Description: A product variant could not be transferred to Shopify; the appended message is the reason Shopify or the integration returned.

Resolution: Review the appended message, correct the indicated variant data, and re-sync the product.

Description: Shopify rejected an inventory-level update — commonly because the location is not linked, or inventory is not tracked at that location.

Resolution: Confirm the location is synced and linked and that inventory tracking is enabled for the item at that location, then re-sync.

Description: The integration could not create the inventory record for the product; the appended message is the reason Shopify returned.

Resolution: Review the appended message, confirm the item and its location are valid, and re-sync.

Description: A mapping that looks up product or variant SKUs in Shopify received no results. This usually means the connection cannot reach the store or the credentials are not valid.

Resolution: Verify the Shopify connection credentials and that the store is reachable (see Shopify Connections and Settings). If the credentials are correct and the store genuinely has no matching products, no action is needed.

Description: A product references a category/collection that could not be created as a prerequisite, so the product transfer fails.

Resolution: Resolve the underlying category error (logged separately) and re-sync the product.

Description: An update was attempted for a collection that is not linked to a Shopify collection id.

Resolution: Sync the category once so it is created and linked in Shopify, then update it.

Description: A Product Category Assignment delete was sent with a Manual Sync id that is not the required <product_id>|<category_id> form.

Resolution: Use the pipe-joined id format on the Manual Sync page (see the Product Category Assignment mapping documentation).

Description: The integration matched an existing Shopify collection by title but could not save the external-id link, which risks a duplicate. This is a warning — the transfer continues.

Resolution: Check for an existing matching collection in Shopify; if a duplicate is created, your MiSP can help remove it.

Description: The integration could not link an incoming Shopify collection to an existing iPaaS.com product category by name.

Resolution: Confirm a matching product category exists in iPaaS.com with the same name, then re-sync.

Description: Shopify accepted the call but returned no order payload, so the integration could not confirm or link the order.

Resolution: Re-sync the order. If it recurs, your MiSP can capture the Shopify response and investigate.

Description: The order was written to Shopify successfully, but a follow-on step failed. The order's Shopify id was saved to iPaaS.com, so this is a partial success.

Resolution: Review the appended message and re-sync. Because the id was saved, the re-sync reconciles against the existing order rather than creating a duplicate.

Description: An order line item references a product that could not be created in Shopify as a prerequisite (this runs when Create Line Item Product as Prerequisite is enabled), so the order fails.

Resolution: Resolve the underlying product error (logged separately), confirm the product data is valid, and re-sync the order.

Description: The integration tried to match an existing Shopify order by the transaction-number metafield and could not save the link, risking a duplicate order. This is a warning — the transfer continues.

Resolution: Confirm the Shopify Metafield for Transaction Number Matching setting points at the correct metafield and that it exists and is filterable in Shopify (see Shopify Connections and Settings). If a duplicate appears, cancel it in Shopify.

Description: The integration matched an incoming order line (or return) to an existing iPaaS.com record by SKU but could not save the link, which risks a duplicate. This is a warning — the transfer continues.

Resolution: Confirm the line SKUs are consistent between systems. If a duplicate appears, your MiSP can help reconcile it.

Description: The order has no payment transactions available to map for the given authorization.

Resolution: Confirm the order actually has payment data in the source; if a payment mapping is required for your flow, ensure the source order includes it.

Description: The payment authorization code referenced by the transfer does not match any authorization on the order.

Resolution: Confirm the authorization value on the source order is correct, then re-sync.

Description: Before a return is created, the integration confirms the transaction identifies an existing, fully-fulfilled Shopify order. This single message covers several causes: the Shopify order id custom field is missing or empty; the order id does not match a Shopify order; the order exists but is not fulfilled; or the order is only partially fulfilled.

Resolution: Confirm the Shopify Order Id custom field holds the correct Shopify order id, that the order exists in Shopify, and that it is fully fulfilled. A return can be created only after every line on the order has shipped, so a partially-fulfilled order must complete first. See Shopify Known Limitations.

Description: The return transaction did not carry the Shopify order id the return needs.

Resolution: Populate the Shopify Order Id custom field on the return transaction with the id of the order being returned.

Description: A required field for creating the return was not provided — the order id, the return line items, or a fulfillment line item id on a return line.

Resolution: Populate the named field on the return transaction and re-sync. Each return line must reference a fulfillment line item from the original order.

Description: An update to an existing return was sent without the Return Id that identifies which Shopify return to change.

Resolution: Ensure the return being updated carries its Shopify Return Id.

Description: A return is created only from a Pending status. Complete and Cancelled are update transitions that apply to a return already created in Shopify.

Resolution: Create the return with status Pending. Use Complete or Cancelled only to update a return that has already synced to Shopify.

Description: An update to an existing return was sent with no status, so the integration cannot determine which lifecycle action to apply.

Resolution: Ensure the transaction status that drives the return is populated before the return is updated.

Description: An update to an existing return supplied a status the return flow does not support. Only Complete (which closes the return) and Cancelled (which cancels it) are valid on an update; Pending is valid only when the return is first created.

Resolution: Use Complete or Cancelled to update a return, and Pending only to create one. Map your source statuses onto these values (for example with a Lookup Translation) so an unsupported state is caught before it reaches the return flow.

Description: When a return line's reason is OTHER, Shopify requires an accompanying note describing the reason.

Resolution: Populate the return line's reason-note field whenever its reason is OTHER.

Description: A return shipping fee was partially specified — an amount without a currency code, or a currency code without an amount.

Resolution: Supply both the return shipping fee amount and its currency code, or neither.

Description: The return reason must be one of Shopify's fixed values, spelled exactly in upper-snake-case. A human-readable reason (for example "Other") or the right word in the wrong case (for example "Other" instead of OTHER) is rejected. This is surfaced through the shared Shopify field-error message (SHPY-EXTN-1003).

Resolution: Map the return reason to one of SIZE_TOO_SMALL, SIZE_TOO_LARGE, UNWANTED, NOT_AS_DESCRIBED, WRONG_ITEM, DEFECTIVE, STYLE, COLOR, OTHER, or UNKNOWN. Values are case-sensitive. Map source reasons onto these with a Lookup Translation so an unmapped reason fails visibly in iPaaS.com. When the reason is OTHER, a reason note is also required (see above).

Description: The requested quantity is more than what remains returnable for that fulfillment line item. Returnable quantity is tracked per fulfillment (shipment), not per order line, so an order shipped in more than one fulfillment has a smaller per-shipment returnable figure than the order-line quantity.

Resolution: Size the return to the returnable quantity shown in the message. For orders shipped in multiple parts, return against each shipment's available quantity.

Description: Shopify no longer treats the line item as returnable. This happens once every unit of that fulfillment line item has already been returned — a full return already exists for the order.

Resolution: The units on that line are already returned, so a further return cannot be created for them. Confirm you are not re-sending a return that has already synced. To return different units, reference a line that still has returnable quantity.

Description: Shopify rejected the return create or a return status change (close/cancel); the appended messages are the reasons Shopify returned. A common create rejection is an invalid return reason value — see Return reason is not a valid value above. Note that a closed return cannot afterwards be cancelled — Shopify's return lifecycle is one-way.

Resolution: Read the appended Shopify messages and correct the return data, then re-sync. Cancel a return only while it is still open. See Shopify Known Limitations.

Description: Shopify accepted the return call but returned no payload, so the integration could not confirm or link the return.

Resolution: Re-sync the return. If it recurs, your MiSP can capture the Shopify response and investigate.

Description: A return line references a SKU that either is not a valid product or is not present on the referenced Shopify order, so the return line cannot be created.

Resolution: Confirm the return line's SKU matches a product that was on the original order, then re-sync.

Description: The return line does not carry the Shopify order id needed to locate the order it belongs to.

Resolution: Populate the Shopify Order Id custom field on the return (and its lines) with the id of the order being returned, then re-sync.

Description: The SKU is a valid product on the order, but it has no matching fulfillment line item — the unit was never shipped, or has already been returned, so it is not returnable.

Resolution: Return only line items that were fulfilled and remain returnable. If the item has not shipped yet, it cannot be returned until it does.

Description: A return captured from Shopify references an order that has not been transferred to iPaaS.com, so there is no parent Transaction to attach the return to.

Resolution: Ensure the original order has transferred to iPaaS.com before its return is captured. Once the order exists in iPaaS.com, re-deliver the return.

Description: Shopify requires a country to create or update a location. This means the iPaaS.com Location's address country did not resolve to a value the integration could send — the CountryCode mapping was empty.

Resolution: Set the iPaaS.com Location address country to a value Shopify recognizes, and confirm the CountryCode mapping (sourced from the address country) is populated.

Description: Shopify enforces unique location names, including across deactivated locations. When the integration tries to create a location whose name already exists in Shopify, Shopify rejects the create with the [TAKEN] code on input.name.

Resolution: This collection's Collision Handling Method should be set to Update and Link, which recovers automatically — the integration finds the existing Shopify location by its exact name (including deactivated locations), links it, and completes as an update instead of creating a duplicate. If you still see this error, confirm the Collision Handling Method on the mapping collection is Update and Link and that the iPaaS.com Location name matches the Shopify location name exactly (matching is case-insensitive but otherwise exact).

Description: Shopify rejected the location create, update, or activation for a reason other than a duplicate name. The bracketed [CODE], field, and message are returned by Shopify and identify the problem — for example an unrecognized country. Activation additionally requires Shopify Admin GraphQL API version 2026-04 or later.

Resolution: Read the [CODE] / field / message and correct the indicated value on the iPaaS.com Location. For activation failures, ensure the connection's API Version is 2026-04 or later. See Shopify Known Limitations.

Description: The location collection's collision matching is configured to match on a field the integration does not support for locations.

Resolution: Confirm the location collection's collision configuration; location matching is by name.

Description: A webhook was requested for a scope that has no corresponding Shopify GraphQL topic, so the subscription cannot be created.

Resolution: Confirm the configured webhook scope is one Shopify supports. If you need a scope that is not mapped, your MiSP can raise it with iPaaS.com Support.

Description: Shopify rejected the webhook subscription create or delete; the appended messages are the reasons Shopify returned.

Resolution: Review the appended messages. If the cause is unclear, your MiSP can investigate with iPaaS.com Support.

Description: A company-contact relationship references a customer by its Shopify id, but no customer with that external id exists in iPaaS.com yet, so the relationship cannot be created.

Resolution: Ensure the related customer has transferred to iPaaS.com first, then re-sync the relationship.

Description: A customer-company relationship references a company by its Shopify id, but no company with that external id exists in iPaaS.com yet, so the relationship cannot be created.

Resolution: Ensure the related company has transferred to iPaaS.com first, then re-sync the relationship.

Description: The integration could not find the Shopify metafield identified by its parent type, parent id, and key, so it cannot be read or updated.

Resolution: Confirm the metafield exists in Shopify for that record and that its key and namespace match what the mapping expects, then re-sync.

Shopify Connections and Settings

Shopify Known Limitations

iPaaS.com to Shopify Order Return Mapping Documentation

Understanding iPaaS.com API Error Codes