Summary
This mapping family transfers order return records (return-type transactions) from Shopware to iPaaS.com. The parent Add/Update Shopware Order Return TO iPaaS.com collection creates and updates return transactions when triggered by Shopware return webhook events or by Manual Sync, and links each return back to the original order it was raised against so it appears under the Related Transactions section of that order in iPaaS.com. Its child collections move the return's line items, address, excise tax, and calculated tax alongside the return in a single transfer.
ID Format
Manual Sync ID Format
Returns are transferred from the iPaaS.com Manual Sync page by entering the Shopware order ID of the originating order. The integration then transfers the matching return together with its line items, address, and taxes. A concrete example order ID is 01915630e5db7214ab1ab2dc71608955.
External ID Format
The return's primary human-readable identifier in iPaaS.com is the return number, derived from the Shopware return identifier (the portion before the underscore suffix) and stored as the Transaction Number. This is the value subscribers use to find and reconcile the return in iPaaS.com.
Deleted Record Support
This family does not include a Delete collection. Return deletions in Shopware are not propagated to iPaaS.com by default. Status changes on a return are reflected through Add/Update transfers: as a return moves through its lifecycle, order-state events drive updates to the return's iPaaS.com status (for example, to Cancelled or Complete) rather than removing the record.
Mapping Collection Status
All collections in this family are Enabled.
Trigger Events
The parent Add/Update Shopware Order Return TO iPaaS.com collection runs when a subscribed Shopware order event fires for a return (Automatic transfer) or when a return is transferred from the iPaaS.com Manual Sync page.
The child collections (Return Line Item, Order Address, Return Excise Tax, Return Calculated Tax) have no independent trigger. They run automatically as part of each parent return transfer, whether that transfer was started by a Shopware webhook or by Manual Sync.
Duplicate or Conflicting Mappings
This family transfers order returns from Shopware to iPaaS.com. The following collections operate on return data in the opposite direction or on closely related records, and should be reviewed before enabling both directions:
Add/Update Shopware Order Return FROM iPaaS.com: Creates and updates order returns in Shopware from iPaaS.com data — the inbound counterpart of this family.
Add/Update Shopware Order TO iPaaS.com: Transfers standard orders to iPaaS.com. Returns are linked back to the original order this collection produces; standard orders themselves are deliberately excluded from the return collection by its filter.
Important: Before enabling this outbound return family alongside the inbound Add/Update Shopware Order Return FROM iPaaS.com collection, review and customize your mapping collection filters to prevent circular updates. Define clearly which system is the source of truth for return data. If both directions are active with default mappings, changes may propagate back and forth between the Order Return TO collection and the Order Return FROM collection.
Unmapped Field Overwrite Risk
The iPaaS.com API performs a full record replace when updating Transaction records, and the collections in this family handle both Add and Update. Standard fields that are not mapped in a collection are overwritten with an empty value on each Update transfer unless a mapping is added to preserve them. The unmapped fields per record type are:
Transaction (parent return): CompanyId, DiscountAmount, ShippingAmount, TransactionCreatedDateTime. The server-managed identifiers Id, ParentId, and TransactionId, and the server-set TransactionUpdatedDateTime timestamp, are managed by iPaaS.com itself and are not at risk.
Transaction Line (return line item): DiscountPercent, EstimatedTaxAmount, QtyShipped, Weight.
Transaction Address (return address): ShipDate, ShippingAmount, ShippingMethodDescription.
Transaction Tax (excise tax / calculated tax): OriginalAmount, TaxPercent.
To preserve writeable values, split the combined Add/Update collection into separate Add and Update collections and, in the Update collection, add a Dynamic Formula mapping that uses the DestinationValue function to carry the existing iPaaS.com value forward — for example, DestinationValue.ShippingAmount mapped to the iPaaS.com ShippingAmount field.
Supported Child Collections
Add/Update Shopware Order Return Line Item TO iPaaS.com (Transaction Line): Transfers the return's product line items — unit price, quantity, original unit price, discount, extended price, type, status, SKU, description, and tax percent.
Add/Update Shopware Order Address TO iPaaS.com (Transaction Address): Transfers the return's addresses, including recipient name, company, street lines, city, postal code, country, region, and billing/shipping flags.
Add/Update Shopware Order Return Excise Tax TO iPaaS.com (Transaction Tax): Creates a single excise tax row carrying the total excise tax summed across the return's line items.
Add/Update Shopware Order Return Calculated Tax TO iPaaS.com (Transaction Tax): Creates a single calculated tax row carrying the total calculated tax summed across the return's line items.
The child records are linked to the parent return record that the parent transfer creates or updates in iPaaS.com.
Shopware Caveats
Webhook workflow actions require Enterprise Shopware: The automatic-transfer workflows can only be created on Enterprise editions of Shopware. Subscribers on other editions should rely on Manual Sync.
Return state names are language-dependent: Shopware returns the state name in the store's configured language, so the Status translation matches both the English and German spellings of each state. Stores configured in another language may need the status mapping extended so their state names map to the correct iPaaS.com status; otherwise those returns default to Pending.
Per-line discount amount is not native: The DiscountAmount value on a return line item requires the Shopware Admin API to be customized to expose a per-line discount on the line item price object (a
line_item_discountextension carrying adiscount_amountvalue). Subscribers or their MiSP should configure this extension before relying on the field; without it, the discount amount is empty.Tax percent on lines with no tax rules: The line TaxPercent is the sum of the tax rates on the return line. If a line carries no tax rules, the tax percent is 0 and the line still transfers.
SKU and Description resolution: A return line item's Sku and Description are resolved from its source order line item in Shopware. If the source line item cannot be resolved, the corresponding value is left empty.
Country and Region resolution: Address Country and Region names are resolved from Shopware's country and country-state IDs. If an ID is invalid or not found, the corresponding name is left empty.
Billing and shipping flags depend on the parent order: The IsPrimaryBilling flag is derived from the parent order's billing address; if it cannot be resolved, the flag is false for every address. The IsPrimaryShipping flag and ShippingMethod name are derived from the parent order's tracking information; if the parent order has no tracking record, the shipping flag is false and the shipping method name is empty.
Derived tax rows: The excise tax and calculated tax rows are derived from the return's line item data, not from dedicated Shopware tax records. Each per-line value originates from the line item's tax data in Shopware; if that data is not present, the per-line contribution is zero.
iPaaS.com Caveats
A return is linked to its original order and customer in iPaaS.com by existing cross-platform links. The original order must already have been transferred to iPaaS.com for the parent link to resolve; if it has not, no parent order can be attached to the return, and the return appears in iPaaS.com without the Related Transactions link until the original order is transferred.
When a return is transferred and the customer on the original order has not yet been linked, the integration transfers that customer record first — even when customer webhooks are disabled — so the return can be attached to the correct iPaaS.com customer. To prevent customer records from being created or updated during return transfers, disable the customer transfer mapping collections.
Child collections run only as part of a parent return transfer. They cannot be triggered independently from the Manual Sync page; transfer the parent return to move its line items, address, and taxes.
The return line item Status is always set to Pending, regardless of the Shopware return state.
A single excise tax row and a single calculated tax row are created per return, each carrying the combined amount across all line items; individual per-line tax amounts are not transferred as separate tax rows. When a summed tax total is zero, the corresponding tax row is not created.
Subscribers should stagger large manual jobs and rely on the configured throttle limits for the subscription when transferring returns in bulk.
Setup Requirements
For Automatic transfer, subscribers or their MiSP must subscribe to the relevant Shopware order events on the Inbound Data Flows (External Webhooks) page of the Shopware subscription in iPaaS.com. Webhooks do not activate automatically — the relevant events must be subscribed before automatic transfers occur. Subscribing creates a workflow in Shopware that sends a webhook to iPaaS.com after the corresponding event; clearing the Inbound Data Flow toggle removes that workflow. Webhook workflow actions are only available in Enterprise editions of Shopware; on non-Enterprise editions, use Manual Sync instead.
Integration Flow
A subscribed Shopware order event fires for a return (Automatic), or a subscriber enters the Shopware order ID on the iPaaS.com Manual Sync page (Manual).
iPaaS.com receives the trigger and retrieves the return from Shopware.
The return passes the parent collection's filter (transaction type is order_return); standard orders and deposit orders are excluded and handled by their own collections.
The integration resolves the parent order link (the original order's iPaaS.com transaction) and the customer link. If the customer on the original order is not yet linked, that customer record is transferred first so the link can be established.
The parent return record is created or updated in iPaaS.com, with its return number, type, status, totals, taxes, customer email, and system/parent/customer links.
The child collections run within the same transfer: return line items, the return address, the excise tax row, and the calculated tax row are added to the parent return.
The return is linked back to the original order and appears under the Related Transactions section of that order in iPaaS.com.
Mappings
Add/Update Shopware Order Return TO iPaaS.com
Mapping Filter
Type == "order_return"
Filter Description. This collection processes only records whose transaction type is order_return, so it transfers order returns only. Standard orders are handled by the separate Add/Update Shopware Order TO iPaaS.com collection, and deposit orders by the separate Add Shopware Order Deposit TO iPaaS.com collection. Records of any other type do not pass and are not transferred by this collection. The filter does not throw an exception.
Description: Transfers the order return's core commercial values and resolves its links to the iPaaS.com system, original order, and customer.
Mapping Type | Source Field (Shopware) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| TransactionNumber | recommended — sets the iPaaS.com transaction number to the return number, taking the portion of the Shopware return identifier before the underscore suffix; this is the human-readable identifier used to reconcile the return and the value entered on Manual Sync. |
Static |
| Type | recommended — identifies the record as an order return rather than a standard order or deposit. |
Dynamic Formula |
| SystemId | recommended — associates the return with the correct connected Shopware system; resolves automatically at transfer time. Leave this mapping in place. |
Dynamic Formula | Resolve parent order link | ParentId | recommended — links the return to the original order it was raised against, so it appears under Related Transactions on that order. If the original order has not been transferred, no parent link resolves. |
Dynamic Formula | Resolve customer link | CustomerId | recommended — links the return to the correct iPaaS.com customer, resolved from the customer on the original order; the customer is transferred first if not yet linked. |
Dynamic Formula | Resolve email by order | EmailAddress | recommended — the customer's email address, resolved from the original order; stored only when a non-empty email is found. |
Dynamic Formula | Translate return state | Status | recommended — translates the Shopware return state into an iPaaS.com status (Complete, Cancelled, or Pending). |
Dynamic Formula |
| TotalQty | recommended — the total item quantity across all return line items; 0 when the return has no line items. |
Field | AmountTotal | Total | recommended — the return amount total, so the grand total reconciles in iPaaS.com. |
Field | Price_CalculatedTaxes | TaxAmount | recommended — the return's calculated taxes, so the tax breakdown is complete. |
Field | AmountNet | Subtotal | recommended — the return net amount (line-item value before tax). |
// ParentId return await GetSpaceportIdAsync(OrderId, "Transaction", SpaceportSystemId);
// CustomerId var customerID = await GetCustomerIdByOrderId(OrderId); return await GetSpaceportIdAsync(customerID, "Customer", SpaceportSystemId);
// EmailAddress String email = await GetEmailByOrderId(OrderId); if(!string.IsNullOrWhiteSpace(email)) return email; return null;
// Status
var status = await TransactionStateNameFromId(StateId);
switch(status)
{
case "Abgebrochen":
case "Cancelled":
case "Order clearance denied":
return "Cancelled";
break;
case "Abgeschlossen":
case "Done":
return"Complete";
break;
default:
return "Pending";
break;
}Add/Update Shopware Order Return Line Item TO iPaaS.com
Mapping Filter
Type!=null && Type!="promotion_line_item"
Filter Description. This filter transfers only product line items. Any line whose type is empty (null) and any line whose type is promotion_line_item is skipped, so promotion lines on the Shopware order return are not created as Transaction Lines on iPaaS.com. All other line items pass. The filter does not throw an exception.
Description: Transfers each qualifying return line item as a Transaction Line on the iPaaS.com return.
Mapping Type | Source Field (Shopware) | Destination Field (iPaaS.com) | Description |
Field | Price_UnitPrice | UnitPrice | optional — the return line item unit price. |
Field | Quantity | Qty | optional — the return line item quantity. |
Field | Price_UnitPrice | OriginalUnitPrice | optional — preserves the pre-discount unit price for reference. |
Field | Price_DiscountAmount | DiscountAmount | optional — the per-line discount amount; requires a customized Shopware Admin API exposing a |
Field | Price_TotalPrice | ExtendedPrice | optional — the return line item total price. |
Static |
| Type | optional — identifies the row as a product line. |
Static |
| Status | optional — always sets the line status to Pending for every transferred return line item. |
Dynamic Formula | Resolve description | Description | optional — the description resolved from the line item's source order line item; empty if it cannot be resolved. |
Dynamic Formula | Resolve SKU | Sku | optional — the SKU resolved from the line item's source order line item; empty if it cannot be resolved. |
Dynamic Formula | Sum tax rates | TaxPercent | optional — the sum of the tax rates on the return line item; 0 when the line carries no tax rules, and the line still transfers. |
// Description String description = await GetLineItemDescription(OrderLineItemId_Return); if(!string.IsNullOrWhiteSpace(description)) return description; return null;
// Sku
String sku = await GetLineItemSku(OrderLineItemId_Return);
if(!string.IsNullOrWhiteSpace(sku))
return sku;
return null;// TaxPercent
double result = 0;
if(Price_TaxRules != null && Price_TaxRules.Count > 0){
foreach (var tax in Price_TaxRules){
if (tax.TaxRate != null) {
result = result + tax.TaxRate;
}
}
}
if (result == 0) {
}
return result;Add/Update Shopware Order Address TO iPaaS.com
Description: Transfers each of the return's addresses to iPaaS.com as a Transaction Address, resolving country, region, billing/shipping flags, and the shipping method name.
Mapping Type | Source Field (Shopware) | Destination Field (iPaaS.com) | Description |
Field | FirstName | FirstName | optional — the recipient first name on the address. |
Field | LastName | LastName | optional — the recipient last name on the address. |
Field | Company | Company | optional — the company name on the address, typically populated for business addresses. |
Field | Street | Address1 | recommended — the primary street line, recommended for deliverable addresses. |
Field | AdditionalAddressLine1 | Address2 | optional — the second street line. |
Field | AdditionalAddressLine2 | Address3 | optional — the third street line. |
Field | City | City | recommended — the address city, recommended for deliverable addresses. |
Field | Zipcode | PostalCode | recommended — the postal/ZIP code, recommended for deliverable addresses. |
Dynamic Formula | Resolve country name | Country | recommended — the country name resolved from the Shopware Country ID; empty if the ID is invalid or not found. |
Dynamic Formula | Resolve state name | Region | optional — the state/region name resolved from the Shopware Country ID and Country State ID; empty if either ID cannot be resolved. |
Dynamic Formula | Resolve billing flag | IsPrimaryBilling | optional — true when this address matches the parent order's billing address; false if the billing address cannot be resolved. |
Dynamic Formula | Resolve shipping flag | IsPrimaryShipping | optional — true when this address matches the shipping address on the parent order's first tracking record; false when the order has no tracking information. |
Dynamic Formula | Resolve shipping method | ShippingMethod | optional — the shipping method name for the order's shipping address; empty for non-shipping addresses or when the order has no tracking information. |
// Country return await CountryNameFromId(CountryId);
// Region return await StateNameFromId(CountryId,CountryStateId);
// IsPrimaryBilling
string billingAddressId = await GetBillingAddressIdByOrderId(Parent.OrderId);
if (!string.IsNullOrWhiteSpace(billingAddressId) && Id.StartsWith(billingAddressId)) { return true; } return false;// IsPrimaryShipping
if (Parent.Transaction_Tracking != null && Parent.Transaction_Tracking.Count > 0){
var shippingAddressId = Parent.Transaction_Tracking[0].ShippingOrderAddressId;
if (Id.StartsWith(shippingAddressId)){return true;}
}
return false;// ShippingMethod
if (Parent.Transaction_Tracking != null && Parent.Transaction_Tracking.Count > 0){
var shippingAddressId = Parent.Transaction_Tracking[0].ShippingOrderAddressId;
if (Id.StartsWith(shippingAddressId)){
var methodId = Parent.Transaction_Tracking[0].ShippingMethodId;
return await GetShippingMethodNameById(methodId);
}
}
return null;Add/Update Shopware Order Return Excise Tax TO iPaaS.com
Mapping Filter
SumFieldFromCollection(Parent.Transaction_Line, "Payload_ExciseTaxAmount_Total") <> 0
Filter Description. This filter gates whether the excise tax row is created at all. The SumFieldFromCollection function sums the Payload_ExciseTaxAmount_Total value across all of the return's line items, and the row is created only when that total is not zero. Returns with no excise tax produce no excise tax row on iPaaS.com. The filter does not throw an exception.
Description: Creates a single excise tax Transaction Tax row on the return, carrying the total excise tax summed across all line items.
Mapping Type | Source Field (Shopware) | Destination Field (iPaaS.com) | Description |
Static |
| Authority | optional — labels the tax authority as Excise Tax for the row this collection creates. |
Dynamic Formula |
| Amount | optional — the total excise tax for the return, summed across every line item; the per-line value originates from the line item's excise calculated taxes data in Shopware. |
Add/Update Shopware Order Return Calculated Tax TO iPaaS.com
Mapping Filter
SumFieldFromCollection(Parent.Transaction_Line, "Price_CalculatedTaxes") <> 0
Filter Description. This filter gates whether the calculated tax row is created at all. The SumFieldFromCollection function sums the Price_CalculatedTaxes value across all of the return's line items, and the row is created only when that total is not zero. Returns with no calculated tax produce no calculated tax row on iPaaS.com. The filter does not throw an exception.
Description: Creates a single calculated tax Transaction Tax row on the return, carrying the total calculated tax summed across all line items.
Mapping Type | Source Field (Shopware) | Destination Field (iPaaS.com) | Description |
Static |
| Authority | optional — labels the tax authority as Calculated Tax for the row this collection creates. |
Dynamic Formula |
| Amount | optional — the total calculated tax for the return, summed across every line item; the per-line value originates from the line item's calculated taxes data in Shopware. |
Error Handling
Errors surface in Dashboard / Integration Monitoring / Error Logs.
Dependent customer creation fails: When a return is transferred and the customer on the original order is not yet linked, the integration transfers that customer first. If the dependent customer cannot be created, the return transfer fails. Resolution: confirm the original order's customer can be transferred, or disable the customer transfer mapping collections if customer records should not be created during return transfers.
Shopware API temporarily unavailable: If the Shopware API is unavailable when a transfer is triggered, the transfer fails. Resolution: retry the record by triggering a new webhook event or by using Manual Sync; child records are retried by re-triggering the parent return transfer.
Testing & Validation
Test Scenarios
Create a new return in Shopware and confirm it transfers to iPaaS.com as a return-type transaction with the return number, type, status, totals, and taxes populated.
Update an existing return's state in Shopware (for example, complete or cancel it) and confirm the iPaaS.com status translates correctly to Complete, Cancelled, or Pending.
Verify the return links back to its original order under the Related Transactions section of that order in iPaaS.com, and that the customer link resolves.
Transfer a return for an original order that has not yet been transferred, and confirm the return appears without the parent order link until the original order is transferred.
Transfer a return whose customer is not yet linked, and confirm the customer record is transferred first.
Confirm child records transfer with the parent: return line items (with promotion lines excluded), the return address with resolved country/region and billing/shipping flags, and the excise and calculated tax rows.
Confirm a return with zero excise tax produces no excise tax row, and a return with zero calculated tax produces no calculated tax row.
Use Manual Sync with the Shopware order ID and confirm the return and all its children transfer together.
Validation Checklist
The return transaction number matches the Shopware return number (portion before the underscore suffix).
The return type is set to Return and the status reflects the Shopware return state.
TotalQty, Total, TaxAmount, and Subtotal reconcile against the Shopware return.
The parent order and customer links resolve, and the return appears under Related Transactions on the original order.
Return line items exclude promotion lines; SKU and description resolve from the source order line items where available.
The address shows the correct country, region, billing flag, shipping flag, and shipping method name.
Excise and calculated tax rows are present only when their summed totals are non-zero.
For Update transfers, unmapped fields that should be preserved are not blanked (apply the DestinationValue technique where required).
Additional Notes
Standard orders and deposit orders are not processed by this family; they are transferred by the separate Add/Update Shopware Order TO iPaaS.com and Add Shopware Order Deposit TO iPaaS.com collections respectively.
If a store is configured in a language other than English or German, subscribers or their MiSP should extend the matched return state names so the new spellings map to the correct iPaaS.com status; otherwise those returns default to Pending. Subscribers should validate this behavior in a staging environment before relying on it in production.
These limitations are inherent to the current design of the integration and the capabilities of the Shopware API, and they apply to all subscribers at the time this documentation was written.