Summary

Shopify order returns can be imported into iPaaS.com as Transactions of type Return, linked to the original order's Transaction. Two collection pairs handle this: Add Shopify Order Return TO iPaaS.com with its child Add Shopify Order Return Line TO iPaaS.com import a return for the first time, and Update Shopify Order Return TO iPaaS.com with its child Update Shopify Order Return Line TO iPaaS.com update a return that iPaaS.com already holds when it is transferred again. Whether an incoming return is added or updated is decided by whether it is already linked in iPaaS.com. The return's Shopify state is translated to an iPaaS.com status on both paths.

ID Format

Manual Sync ID

On the iPaaS.com Manual Sync page, enter the Shopify return id to import that return.

External ID (saved after sync)

On first import, iPaaS.com saves the Shopify return id as the external-id link for the transaction on a dedicated external-id record. Later transfers of the same return are matched through that link and routed to the Update collections, so the same iPaaS.com Transaction is refreshed rather than duplicated. The return's Shopify name (for example #1001-R1) is separately stored as the iPaaS.com Transaction number for visibility.

Deleted Record Support

Deleting a return is not supported in this direction. Returns are imported and updated; a return removed in Shopify is not deleted from iPaaS.com by this integration.

Custom Field Support

Each captured return line's reason and note are stored on the Shopify Return Line Item Reason and Shopify Return Line Item Reason Note custom fields. These are the same custom fields the return-from-iPaaS.com flow reads, so a reason set in either system is preserved across the round-trip.

Status and Trigger Events

Returns are imported by the Shopify return events subscribed in the subscription's Inbound Data Flows section — Return requested/created, approved, processed, cancelled, closed, declined, reopened, and updated. Which event fired does not decide Add versus Update: an unlinked return is added, an already-linked one is updated. No automatic transfers occur until those subscriptions are enabled; Manual Sync is available at any time.

The return Status is resolved through the Shopify Transaction Return Status To iPaaS lookup translation, which maps every Shopify return state:

Shopify return state	iPaaS.com status
OPEN	Pending
REQUESTED	Pending
CLOSED	Complete
CANCELED	Cancelled
DECLINED	Cancelled

Confirm the translation is populated, and adjust the pairings if your process needs different iPaaS.com statuses.

Duplicate or Conflicting Collections

The outbound Add/Update Shopify Order Return FROM iPaaS.com collection writes the same returns from iPaaS.com to Shopify. Before enabling automatic transfers in both directions, review and customize the mapping filters and Add/Update settings so each system's role as source of truth is clear.

Collision handling. The external-id record that stores the Shopify return id is the match used to route subsequent transfers of a return to the Update collections, so an already-imported return is refreshed rather than duplicated.

Supported Child Collections

Add Shopify Order Return Line TO iPaaS.com: captures the returned items (SKU, description, quantity, status, reason, and note) on first import.
Update Shopify Order Return Line TO iPaaS.com: refreshes the return's line items when a return is re-imported.

System Caveats

The original order must exist in iPaaS.com. A return is linked to the original order's Transaction; a return whose order has not been imported is rejected rather than imported as an orphan.
Header values are preserved on re-import; line monetary values are not. The Update header collection re-supplies the header values iPaaS.com already holds so subscriber edits survive, but the Update line collection does not preserve per-line monetary values — they are reset to the incoming Shopify values. If only the return status needs to be kept current, the line Update collection can be disabled or removed during implementation so existing line values are left untouched.
Status is the value that changes on update. On re-import the header re-resolves only Status from the incoming Shopify state; the remaining header fields are preserved.

Integration Flow

When a Shopify return is transferred to iPaaS.com:

The return is received from a subscribed return event (or entered on Manual Sync by return id).
The return is matched to the original order's iPaaS.com Transaction, its parent. If that order is not present in iPaaS.com, the transfer is rejected with an error.
If the return is not yet linked in iPaaS.com, the Add collections create a new Return Transaction and its lines and save the external-id link. If the return is already linked, the Update collections refresh the existing Transaction in place — the header preserves its stored values and re-resolves Status, and the lines are refreshed.

Mappings

Add Shopify Order Return TO iPaaS.com

Mapping Filter

if (Type != "return")
{
    return false;
}long? parentTransactionId = GetSpaceportId(Return_OrderId, "Transaction", SpaceportSystemId);
if (parentTransactionId != null)
{
    return true;
}
throw new Exception($"Return Transfer Failed: No parent Transaction exists in iPaaS for Return_OrderId '{Return_OrderId}'.");

Filter Description. Only transactions of type Return are processed; any other type is skipped. For a return, the filter looks up the original order's Transaction in iPaaS.com. If it is found, the return passes. If it is not found, the return is rejected with the message "Return Transfer Failed: No parent Transaction exists in iPaaS for Return_OrderId '{Return_OrderId}'." — import the original order first.

Mapping Type	Source Field	Destination Field	Description
Dynamic Formula	Connection system id	SystemId	Records which Shopify connection the return came from. Set automatically.
Field	Return_Name	TransactionNumber	The return's Shopify name, stored as the iPaaS.com Transaction number. Required.
Dynamic Formula	Original order Transaction	ParentId	Links the return to the original order's iPaaS.com Transaction. Required; the order must already be in iPaaS.com.
Dynamic Formula	Customer on the order	CustomerId	Associates the return with the same customer as the original order; captured without a customer if none resolves.
Static	`Return`	Type	Marks the Transaction as a return. Required.
Lookup Translation	Shopify Transaction Return Status To iPaaS	Status	Translates the Shopify return state to an iPaaS.com status. Required.
Dynamic Formula	Email on the order	EmailAddress	Captures the customer email from the original order.
Field	Return_TotalQuantity	TotalQty	The total quantity on the return. Required.
Field	CreatedAt	TransactionCreatedDateTime	The date and time the return was created in Shopify.

Add Shopify Order Return Line TO iPaaS.com

This child collection has no mapping filter; every line of an imported return is captured.

Mapping Type	Source Field	Destination Field	Description
Field	ReturnLineItem_ReturnReason	Shopify Return Line Item Reason (custom field)	Captures the return reason into the iPaaS.com custom field; round-trips with the return-from-iPaaS.com flow.
Field	ReturnLineItem_ReturnReasonNote	Shopify Return Line Item Reason Note (custom field)	Captures the return reason note into the iPaaS.com custom field.
Static	`Product`	Type	Marks the line as a product line. Required.
Dynamic Formula	Parent return status	Status	Sets the line status from the parent return's state (OPEN/REQUESTED → Pending, CLOSED → Complete, CANCELED/DECLINED → Cancelled).
Field	Sku	Sku	The returned item's SKU. Required.
Field	Title	Description	The returned item's title, stored as the line description.
Field	ReturnLineItem_Quantity	Qty	The quantity returned for the line. Required.

Update Shopify Order Return TO iPaaS.com

Mapping Filter

if (Type != "return")
{
    return false;
}long? parentTransactionId = GetSpaceportId(Return_OrderId, "Transaction", SpaceportSystemId);
if (parentTransactionId != null)
{
    return true;
}
throw new Exception($"Return Transfer Failed: No parent Transaction exists in iPaaS for Return_OrderId '{Return_OrderId}'.");

Filter Description. Identical to the Add collection: only transactions of type Return whose original order exists in iPaaS.com are processed; a return whose parent order is missing is rejected with "Return Transfer Failed: No parent Transaction exists in iPaaS for Return_OrderId '{Return_OrderId}'." This collection updates a return that is already linked in iPaaS.com.

Because the iPaaS.com API replaces the whole record on update, this collection re-supplies each header value it should keep from the value already stored on the iPaaS.com Transaction; only Status is re-resolved from the incoming Shopify state.

Mapping Type	Source Field	Destination Field	Description
Dynamic Formula	Existing iPaaS.com value	SystemId	Preserves the stored value on update.
Dynamic Formula	Existing iPaaS.com value	TransactionNumber	Preserves the stored Transaction number. Required.
Dynamic Formula	Existing iPaaS.com value	ParentId	Preserves the link to the original order's Transaction.
Dynamic Formula	Existing iPaaS.com value	CustomerId	Preserves the customer association.
Dynamic Formula	Existing iPaaS.com value	Type	Preserves the transaction type.
Lookup Translation	Shopify Transaction Return Status To iPaaS	Status	Re-resolved from the incoming Shopify state — the one field this collection changes. Required.
Dynamic Formula	Existing iPaaS.com value	EmailAddress	Preserves the customer email.
Dynamic Formula	Existing iPaaS.com value	TaxAmount	Preserves the header tax amount.
Dynamic Formula	Existing iPaaS.com value	ShippingAmount	Preserves the header shipping amount.
Dynamic Formula	Existing iPaaS.com value	Subtotal	Preserves the header subtotal.
Dynamic Formula	Existing iPaaS.com value	Total	Preserves the header total.
Dynamic Formula	Existing iPaaS.com value	TotalQty	Preserves the total returned quantity. Required.
Dynamic Formula	Existing iPaaS.com value	TransactionCreatedDateTime	Preserves the original creation date and time.

Update Shopify Order Return Line TO iPaaS.com

This child collection has no mapping filter; every line of the re-imported return is updated. It maps the same fields as the Add line collection. It does not preserve per-line monetary values — any per-line money held in iPaaS.com is reset to the incoming Shopify values on re-import (see System Caveats).

Mapping Type	Source Field	Destination Field	Description
Field	ReturnLineItem_ReturnReason	Shopify Return Line Item Reason (custom field)	Refreshes the return reason in the iPaaS.com custom field.
Field	ReturnLineItem_ReturnReasonNote	Shopify Return Line Item Reason Note (custom field)	Refreshes the return reason note.
Static	`Product`	Type	Marks the line as a product line. Required.
Dynamic Formula	Parent return status	Status	Sets the line status from the parent return's state.
Field	Sku	Sku	The returned item's SKU. Required.
Field	Title	Description	The returned item's title.
Field	ReturnLineItem_Quantity	Qty	The quantity returned for the line. Required.

Error Handling

Import errors appear in the iPaaS.com error logs. The most common is an orphan return — a return whose original order is not present in iPaaS.com — which is rejected with "Return Transfer Failed: No parent Transaction exists in iPaaS for Return_OrderId '{Return_OrderId}'." Import the original order first. See Shopify Error Messages.

Testing and Validation

Ensure the original order has been imported into iPaaS.com, then create a return against it in Shopify.
Confirm the return imports as a new iPaaS.com Transaction of type Return, linked to the order, with the expected status, lines, and quantities.
Change the return's state in Shopify (for example close it) and confirm the same iPaaS.com Transaction is updated in place with the new status and is not duplicated.
Confirm that header values you have edited in iPaaS.com survive a re-import, and validate the line-value behavior in a staging environment before relying on it in production.

Additional Notes / Out of Scope

Refunds, approvals/declines, and exchanges are not represented as separate records; the return and its lifecycle status are captured.
Line-level monetary values are not preserved when a return is re-imported (see System Caveats).

Shopify to iPaaS.com Order Return Mapping Documentation