Summary
Returns can be created and updated in Shopify from iPaaS.com Transaction data. An iPaaS.com Transaction of type Return that names an existing Shopify order is turned into a Shopify return against that order's shipped items. The tree is led by the Add/Update Shopify Order Return FROM iPaaS.com parent collection, which writes the return header, and one child collection, Add/Update Shopify Order Return Line FROM iPaaS.com, which supplies the items being returned. The tree supports the Add/Update sync type: on the first transfer the return is created in a pending state and linked by saving the Shopify return id; on a later transfer the linked return is closed or cancelled to reflect the source status.
ID Format
Manual Sync ID
On the iPaaS.com Manual Sync page, enter the iPaaS.com Transaction id of the return to send it to Shopify.
External ID (saved after sync)
On a successful transfer, iPaaS.com records the Shopify return id as the external-id link for the transaction on a dedicated external-id record. Subsequent transfers of the same return use that link to update the existing Shopify return rather than creating a second one.
Deleted Record Support
Deleting a return is not supported. This flow creates, closes, and cancels returns; it does not delete Shopify returns, and deleting a return transaction in iPaaS.com is not propagated to Shopify.
Custom Field Support
The flow depends on two kinds of iPaaS.com custom fields:
Shopify_OrderId on the return transaction identifies the Shopify order the return is raised against. It is required.
Shopify Return Line Item Reason and Shopify Return Line Item Reason Note on each return line carry the return reason and note. The return-to-iPaaS.com collections read these same custom fields, so the reason and note round-trip between the two systems.
Status and Trigger Events
Returns are dispatched to Shopify by the iPaaS.com Transaction outbound triggers configured in the subscription's Outbound Data Flows section — the Create trigger dispatches a new return and the Update trigger dispatches a status change. No automatic transfers occur until those subscriptions are enabled; Manual Sync is available at any time.
The transaction Status drives the return's lifecycle action:
Pending creates the return (a return is always created in a pending state).
Complete closes an existing return.
Cancelled cancels an existing return.
Any other value is rejected. Shopify's return lifecycle is one-way — a closed or cancelled return cannot be reopened or re-transitioned.
Duplicate or Conflicting Collections
The opposite direction — importing the same Shopify returns into iPaaS.com — is handled by Add Shopify Order Return TO iPaaS.com (first import) and Update Shopify Order Return TO iPaaS.com (re-delivery). Decide which system is the source of truth for return lifecycle before enabling automatic transfers in both directions.
Collision handling. iPaaS.com routes subsequent transfers of a return through the external-id record that stores the Shopify return id, so an already-linked return is updated rather than duplicated. When this flow closes or cancels a return, the integration records the write so the resulting Shopify webhook is recognized as its own and is not sent back into iPaaS.com as a new transfer — so the two directions do not loop.
Supported Child Collections
Add/Update Shopify Order Return Line FROM iPaaS.com: the items being returned, each identified by SKU and quantity with a return reason and optional note. The lines are created as part of the parent return; the parent return carries the external-id link.
System Caveats
The order must be fully fulfilled. A return can only be created against an order whose items are all fulfilled; an unfulfilled or partially fulfilled order is rejected.
Returnable quantity is per shipment. Shopify tracks returnable quantity per fulfillment, so an order shipped in more than one part has a smaller per-shipment returnable figure than the order-line quantity.
Return reasons are a fixed, case-sensitive list, and a reason of OTHER requires a note.
Return taxes are determined by Shopify. There is no mappable tax field on a return.
Return shipping fee. The fee amount is optional; the currency is sent as a static USD by default and must accompany the amount.
Integration Flow
When a return transaction is transferred to Shopify:
The transaction is checked against the header collection's filter — it must be a Return, carry at least one line, name a valid Shopify order in the Shopify_OrderId custom field, and that order must be fully fulfilled.
Each return line's SKU is validated and matched to a shipped (fulfillment) item on the referenced order.
On the first transfer (status Pending), the return is created in Shopify and linked by saving the Shopify return id as the external id.
On a later transfer, the linked return is updated — Complete closes it, Cancelled cancels it — and the lifecycle write is registered so its echo webhook does not loop back.
Mappings
Add/Update Shopify Order Return FROM iPaaS.com
Mapping Filter
if(Type == "Return" && Lines?.Count > 0)
{var orderId = GetCustomFieldValue(CustomFields,"Shopify_OrderId");
if(orderId != null && !string.IsNullOrWhiteSpace(orderId.ToString())){
bool orderExist = await ShopifyOrderExistAndFulfilled(orderId);
if(orderExist)
return true;}
throw new Exception("Return Transaction can not be created because it does not have valid Shopify Order Id in custom field or the order is not fulfilled.");}
return false;Filter Description. Only transactions whose Type is Return and that carry at least one line are considered. For those, the filter reads the Shopify_OrderId custom field and confirms it names a Shopify order that both exists and is fully fulfilled; if so, the transaction passes. A transaction that is not a Return, or a Return with no lines, is skipped without error. A Return whose Shopify_OrderId is missing, does not match a Shopify order, or names an order that is not fully fulfilled is rejected with the message "Return Transaction can not be created because it does not have valid Shopify Order Id in custom field or the order is not fulfilled."
Mapping Type | Source Field | Destination Field | Description |
Dynamic Formula | Linked Shopify return | Id | Resolves the Shopify return this transaction is already linked to so an update targets the existing return; on the first transfer there is no link and a new return is created. Optional; used automatically on updates. |
Field | Type | Type | Identifies the transaction as a return. Required; the value must be Return. |
Field | Shopify_OrderId (custom field) | Return_OrderId | The Shopify order the return is raised against. Required; the order must exist and be fully fulfilled. |
Field | Status | Return_Status | Drives the lifecycle action — Pending creates, Complete closes, Cancelled cancels. Required. Any other value is rejected. |
Field | ShippingAmount | Return_ShippingFee_Amount | The return shipping fee charged to the customer. Optional; if unmapped, no fee is applied. If mapped, the currency must also be supplied. |
Static |
| Return_ShippingFee_CurrencyCode | The currency of the return shipping fee. Sent as a static USD by default. Placeholder value — replace during implementation: change it to your store's currency if it is not USD. Used only when an amount is mapped. |
Add/Update Shopify Order Return Line FROM iPaaS.com
Mapping Filter
string productId = await GetProductOrVariantIdBySkuAsync(Sku);
if (string.IsNullOrWhiteSpace(productId))
{
throw new Exception($"Return line item cannot be created because SKU '{Sku}' is not valid or not found on the order.");
}var orderId = GetCustomFieldValue(Parent.CustomFields, "Shopify_OrderId");
if (string.IsNullOrWhiteSpace(orderId))
{
throw new Exception("Shopify_OrderId was not found in the custom fields.");
}bool hasFulfillmentLineItem = await HasFulfillmentLineItemForSkuAsync(orderId, Sku);
if (!hasFulfillmentLineItem)
{
throw new Exception($"Return line item cannot be created because SKU '{Sku}' does not have a matching fulfillment line item on the order.");
}return true;Filter Description. Each return line is validated in three steps. First, its Sku must resolve to a valid Shopify product; if not, the line is rejected with "Return line item cannot be created because SKU '{Sku}' is not valid or not found on the order." Second, the parent return must carry a Shopify_OrderId; if it is missing, the line is rejected with "Shopify_OrderId was not found in the custom fields." Third, the SKU must correspond to a shipped (fulfillment) item on that order; if it does not, the line is rejected with "Return line item cannot be created because SKU '{Sku}' does not have a matching fulfillment line item on the order." A line that passes all three is included. Subscribers who prefer off-order lines to be skipped instead of failing the transfer can change this filter to return false rather than throw.
Mapping Type | Source Field | Destination Field | Description |
Field | Sku | Sku | The item being returned. Required; must be a valid Shopify product shipped on the referenced order. |
Field | Qty | ReturnLineItem_Quantity | Units to return. Required; cannot exceed the quantity still returnable for that item (tracked per shipment). |
Field | Shopify Return Line Item Reason (custom field) | ReturnLineItem_ReturnReason | The return reason. Required; must be one of Shopify's fixed values (SIZE_TOO_SMALL, SIZE_TOO_LARGE, UNWANTED, NOT_AS_DESCRIBED, WRONG_ITEM, DEFECTIVE, STYLE, COLOR, OTHER, UNKNOWN), spelled exactly and case-sensitively. Map source reasons with a Lookup Translation. |
Field | Shopify Return Line Item Reason Note (custom field) | ReturnLineItem_ReturnReasonNote | A note describing the reason. Required only when the reason is OTHER; optional otherwise. |
Error Handling
Return errors appear in the iPaaS.com error logs with the usual Unable to process transfer. Reason: … prefix, and are cataloged in Shopify Error Messages — including the order-not-fulfilled and return-line validation messages quoted above, an invalid or missing return status, an invalid return reason, a reason of OTHER without a note, a requested quantity that exceeds the returnable amount, and an attempt to cancel a return that is already closed.
Testing and Validation
In the source system, raise a return against an order that has been created in Shopify and is fully fulfilled, with a valid return reason on each line.
Transfer the return (Manual Sync by Transaction id, or via the enabled Create outbound trigger) and confirm a Shopify return is created against the correct order with the expected lines and quantities.
Update the return's status to Complete and confirm the Shopify return closes; on a separate return, update to Cancelled and confirm it cancels.
Confirm the reason and note captured on the Shopify return match what was sent, and that no duplicate return is created when the same transaction is transferred again.
Additional Notes / Out of Scope
Refunds are not issued by this flow.
Approvals and declines of return requests are not performed.
Exchanges (exchange line items) are not processed.
Return taxes are calculated by Shopify and cannot be set from iPaaS.com.