Summary

This mapping family creates and updates sales order returns in Shopware from iPaaS.com return transactions. The parent collection resolves the originating Shopware order, builds the return record (state, requested-at timestamp, internal comment), and links it to the existing order, while its child collection writes the individual returned line items. A separate update collection, running as part of the order update flow, applies return-delivery (return shipping) tracking and status onto the order's deliveries, supporting both full and partial returns.

ID Format

Manual Sync ID Format

Records are transferred from iPaaS.com to Shopware when an iPaaS.com return transaction targets this Shopware subscription. The return is matched to an existing Shopware order by the Shopware Order ID carried in the iPaaS.com transaction's custom fields — for example 01915b3936a2702f87c4379b0f235b12. A return is only created against an order that already exists in Shopware.

External ID Format

After a return is created, the integration records the link between the iPaaS.com transaction and the Shopware return so a subsequent transfer updates the existing return rather than duplicating it. The parent Id mapping resolves this previously stored external identifier; on a first transfer none exists yet and a new return is created.

Deleted Record Support

Deletions are not propagated by this family. There is no Order Return delete collection in this direction. Removing a return in iPaaS.com does not delete the corresponding return in Shopware; the family creates and updates return records and their lines, and updates return-delivery tracking, only.

Mapping Collection Status

All collections in this family are Enabled.

Trigger Events

Add/Update Shopware Order Return FROM iPaaS.com (parent) and its Order Return Lines child run when an applicable iPaaS.com return transaction targets this Shopware subscription, either through an Outbound Data Flow or a Manual Sync from iPaaS.com.
Update Shopware Order Return FROM iPaaS.com does not trigger on its own; it runs as part of its parent Update Shopware Order FROM iPaaS.com transfer.

Duplicate or Conflicting Mappings

This family creates and updates order returns in Shopware from iPaaS.com data. The following mapping collection operates on order returns in the opposite direction:

Add/Update Shopware Order Return TO iPaaS.com: Transfers Shopware order returns, and their lines, to iPaaS.com.

Important: Before enabling this inbound "FROM iPaaS.com" family alongside the outbound Add/Update Shopware Order Return TO 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 systems.

For the Update Shopware Order Return FROM iPaaS.com collection specifically, note that it is one of two near-identical children of Update Shopware Order FROM iPaaS.com that write tracking and delivery status onto a Shopware order. The other, Update Shopware Order Delivery Status FROM iPaaS.com, updates the forward-delivery (shipping) tracking and status rather than the return shipping delivery. To drive delivery status from the return-update child, leave the order-header-level Order_Delivery_Status mapping null or unmapped, so the header-level status and this child collection do not compete to set the same delivery status.

Supported Child Collections

Add/Update Shopware Order Return Lines FROM iPaaS.com (Order Return Lines): Creates or updates the individual returned line items in Shopware as part of the parent return transfer. Each returned line is resolved to its existing Shopware order line by the parent's Shopware Order ID custom field and the line SKU.
Update Shopware Order Return FROM iPaaS.com (Order Return delivery update): A child of Update Shopware Order FROM iPaaS.com that writes return-delivery (return shipping) tracking, status, shipping method, expected arrival dates, and shipping-cost detail onto an existing Shopware order's deliveries. Each row is keyed on a line item and a quantity so that partial and full returns are both supported.

Shopware Caveats

Returns require an existing Shopware order: A return is only created when its Shopware Order ID resolves to an order that already exists in Shopware. Returns whose order cannot be found are skipped.
Return state and language must exist as named: The return state is resolved from a state name in a specific language. The named state must exist in that language in the target Shopware store. Subscribers or their MiSP running a non-English store should adjust the configured language, and if necessary the state name, to values that exist in their store.
Refund amounts are determined by Shopware, not iPaaS.com: This integration does not apply specific refund amounts supplied by iPaaS.com. Shopware determines the refunded amounts automatically from the original order data, including item prices and shipping costs. Custom refund amounts — including partial refunds or manually specified shipping refunds — are not supported. Subscribers who require exact refund values or shipping refunds should validate this behavior against their expectations before relying on the integration in production, as differences between expected and actual refunded values are escalated to support.
Return lines require an existing, product-linked Shopware order line: A return line is only created when its SKU resolves to a real order line on the parent return's Shopware order. The match is made by the order line's product, not by the SKU stored on the order line, so an order line that was added to the original order as a custom or manual line item — one that carries a SKU but is not linked to a Shopware product — cannot be matched, and its return line is rejected. This happens even when the SKU and a matching product both exist in Shopware. As a result, only product-linked order lines can be returned through this flow at the time this documentation was written; returns for custom or unlinked order lines are not supported. See the Shopware Integration Known Limitations article for details.
Line price comes from the original order line: The returned line is priced from the matching Shopware order line, not from a value supplied by iPaaS.com. The order and the order line for the SKU must both exist in Shopware for the price to resolve.
Return reason is mandatory: A reason is required to create or update a return line. When a return-reason identifier is not mapped directly, both the reason content and the reason key must be supplied so the integration can create the reason. When a valid reason identifier is mapped alongside them, it takes precedence and is used directly, and duplicate reasons are not created.
Existing order required for delivery updates: The return-update child only updates deliveries on an order that already exists in Shopware and is linked to the iPaaS.com transaction. It does not create the order; that is handled by the parent Update Shopware Order FROM iPaaS.com transfer.
Partial deliveries: Partial-delivery handling and updating an existing default delivery in place rely on the Shopware Partial Delivery extension behavior. Subscribers or their MiSP should validate partial-return behavior in a staging environment before relying on it in production.

iPaaS.com Caveats

This family transfers return data into Shopware. When the opposite-direction Add/Update Shopware Order Return TO iPaaS.com collection is also enabled, define which system owns return data so updates do not circulate between the two platforms.
The line item and quantity that gate partial-versus-full handling in the return-update child are read from the iPaaS.com custom fields Line Item Id and Quantity. Subscribers or their MiSP should confirm those custom fields are populated on the transferred tracking records.
Subscribers should stagger large manual jobs and rely on the configured API throttle limits exposed by the subscription when transferring large volumes of returns.

Setup Requirements

For automatic transfer, configure an Outbound Data Flow in iPaaS.com so that applicable return transactions are pushed to this Shopware subscription, and confirm the parent return collection and its children are enabled. The parent return collection and the Order Return Lines child transfer together; the Update Shopware Order Return FROM iPaaS.com child is driven by the Update Shopware Order FROM iPaaS.com transfer, so ensure that order update flow is also configured when return-delivery tracking is required.

Integration Flow

An iPaaS.com return transaction (type "Return" or "Validated Return") is triggered toward this Shopware subscription, via an Outbound Data Flow or a Manual Sync.
The parent collection's filter confirms the transaction type and that the Shopware Order ID custom field resolves to an order that already exists in Shopware; non-matching transactions are skipped.
The integration resolves the originating Shopware order and builds the return record from the mapped fields (state, requested-at timestamp, internal comment, type).
The Id mapping looks up any previously stored external identifier; when one exists the matching Shopware return is updated, otherwise a new return is created.
The Order Return Lines child processes each returned line, resolving the Shopware product and the existing order line by SKU, pricing the line from that order line, setting the line state, quantity, and return reason.
After creation, the integration records the link between the iPaaS.com transaction and the new Shopware return so future transfers update it in place.
Separately, when an Update Shopware Order FROM iPaaS.com transfer runs, the Update Shopware Order Return FROM iPaaS.com child applies return-delivery tracking, status, shipping method, arrival dates, and shipping-cost detail onto the order's deliveries, updating an existing single delivery in place when eligible.

Mappings

Add/Update Shopware Order Return FROM iPaaS.com

Mapping Filter

if(Type == "Return" || Type == "Validated Return"){
    var orderId = GetCustomFieldValue(CustomFields,"Shopware Order ID");
    if(orderId != null && !string.IsNullOrWhiteSpace(orderId.ToString())){
        bool orderExist = await ShopwareOrderExist(orderId);
        if(orderExist)
            return true;
    }    
    throw new Exception("Transaction can not be created because it does not have valid shopware order id in custom field");
}
return false;

Filter Description. This collection processes only return transactions that can be matched to an existing Shopware order. A transaction proceeds only when its Type is "Return" or "Validated Return" and the "Shopware Order ID" carried in its iPaaS.com custom fields resolves, through ShopwareOrderExist, to an order that already exists in Shopware. Transactions of any other type return false and are skipped. A return-type transaction that has a missing or blank "Shopware Order ID", or whose order id does not match an existing Shopware order, throws the verbatim exception "Transaction can not be created because it does not have valid shopware order id in custom field" and the record is rejected with an error recorded in Dashboard / Integration Monitoring / Error Logs. Because of this filter, the mappings that depend on the "Shopware Order ID" can safely assume it is present and valid.

Description: Creates or updates the order return record on the existing Shopware order.

Mapping Type	Source Field (iPaaS.com)	Destination Field (Shopware)	Description
Dynamic Formula	Dynamic Formula	OrderId	required — resolves the existing Shopware order the return is created against, reading the GetCustomFieldValue value of the "Shopware Order ID" custom field.
Dynamic Formula	`await GetStateIdByOrderReturnStateName("In Progress", "English")`	StateId	required — sets the return state; resolves a return-state name in a given language to the Shopware return-state identifier.
Dynamic Formula	`TransactionCreatedDateTime.ToString();`	RequestedAt_Return	required — sets the requested-at timestamp from the date and time the originating iPaaS.com transaction was created.
Static	`"Return created by iPaaS.com"`	InternalComment_Return	optional — writes an informational internal comment onto the Shopware return; the shipped default marks the return as originating from iPaaS.com.
Dynamic Formula	`await GetExternalIdAsync(Id, "Transaction", SpaceportSystemId)`	Id	required — resolves the previously linked Shopware return identifier so an existing return is updated rather than duplicated; returns nothing on a first transfer.
Field	Type	Type	required — carries the transaction type so the integration distinguishes a sales order return from a sales order internally.

Note: The shipped default internal comment is "Return created by iPaaS.com". Subscribers or their MiSP can customize this text or map it from an iPaaS.com source value if a different comment is preferred.

The StateId formula pins an environment-specific state and language. Placeholder value — replace during implementation: "In Progress" / "English" — subscribers or their MiSP running a non-English store should substitute a return-state name and language that exist in their store, otherwise this required lookup resolves to nothing and the return is not created.

Add/Update Shopware Order Return Lines FROM iPaaS.com

Mapping Filter

var orderId = GetCustomFieldValue(Parent.CustomFields, "Shopware Order ID");if(orderId != null && !string.IsNullOrWhiteSpace(orderId.ToString())){    var orderLineId = await GetShopwareOrderLineIdByOrderIdAndProductSku(orderId, Sku);    if(orderLineId != null && !string.IsNullOrWhiteSpace(orderLineId.ToString())){        return true;    }    throw new Exception($"This order line sku {Sku} does not exist in Shopware for this order");}return false;

Filter Description. This collection processes only return lines that match an existing Shopware order line. The filter reads the "Shopware Order ID" from the parent return's custom fields with GetCustomFieldValue, then uses GetShopwareOrderLineIdByOrderIdAndProductSku with that order id and the line Sku to locate the matching order line on the Shopware order. A line proceeds only when a matching order line is found. When the parent's "Shopware Order ID" is present but the line SKU does not resolve to a real order line on that order, the filter throws the verbatim exception "This order line sku {Sku} does not exist in Shopware for this order" (with the actual SKU substituted) and the line is rejected with an error recorded in Dashboard / Integration Monitoring / Error Logs. When the parent has no "Shopware Order ID", the filter returns false and the line is skipped. Because of this filter, the mappings that depend on the order line — including the line price — can safely assume it exists.

Description: Creates or updates each individual returned line item against its existing Shopware order line.

Mapping Type	Source Field (iPaaS.com)	Destination Field (Shopware)	Description
Dynamic Formula	`await GetProductIdBySku(Sku);`	ProductId	required — resolves the Shopware product for the returned line from its SKU.
Dynamic Formula	`return await GetStateIdByOrderLineStateName("Returned");`	StateId	required — resolves the order-line state name to the Shopware order-line state identifier.
Dynamic Formula	Line price lookup	LinePrice	required — prices the returned line from the existing Shopware order line resolved by the parent's "Shopware Order ID" and the line SKU.
Field	Qty	Quantity	required — carries the returned quantity onto the Shopware return line.
Static	`"Line return created by iPaaS.com"`	InternalComment_Return	optional — writes an informational internal comment onto the Shopware return line; the shipped default marks the return line as originating from iPaaS.com.
Static	`"test content for reason from line item mapping"`	Reason_Content_Return	required when no separate ReasonId_Return is mapped — supplies the descriptive content of the return reason.
Static	`"test reason key for reason from line item mapping"`	Reason_ReasonKey_Return	required when no separate ReasonId_Return is mapped — supplies the key of the return reason.

var orderId = GetCustomFieldValue(Parent.CustomFields, "Shopware Order ID");
if(orderId != null && !string.IsNullOrWhiteSpace(orderId.ToString())){
    return await GetShopwareOrderLinePriceByOrderIdAndProductSku(orderId, Sku);
}
//return await GetShopwareOrderLinePriceByOrderIdAndProductSku("01915b3936a2702f87c4379b0f235b12", Sku);

When a valid ReasonId_Return is mapped alongside the reason content and key, the provided reason identifier takes precedence and is used directly; duplicate reasons are not created.

The internal-comment static ships with the default "Line return created by iPaaS.com", which subscribers or their MiSP can customize or map from an iPaaS.com source value.

Placeholder value — replace during implementation: "test content for reason from line item mapping" and "test reason key for reason from line item mapping" are example test content. Subscribers or their MiSP should replace each with real values, map them from real iPaaS.com source values, or supply a valid ReasonId_Return instead before enabling the collection.

Update Shopware Order Return FROM iPaaS.com

Mapping Filter

var lineItemId = GetCustomFieldValue(CustomFields, "Line Item Id");var msNavQuantity = GetCustomFieldValue(CustomFields, "Quantity");if (!string.IsNullOrEmpty(lineItemId) && !string.IsNullOrEmpty(msNavQuantity)){    var iPaaSLineItemQuantity = await GetQuantityOfLineItem(lineItemId,Parent.Id);    if (Int64.TryParse(msNavQuantity, out var msNavQty))    {        return msNavQty < iPaaSLineItemQuantity;    }}return false;

Filter Description. This partial-shipment validating filter gates the transfer into partial-versus-full delivery handling. It reads the iPaaS.com custom fields "Line Item Id" and "Quantity" with GetCustomFieldValue. A row proceeds only when both custom fields are populated and the "Quantity" parses as an integer: GetQuantityOfLineItem resolves the line's ordered quantity, and the row passes only when the returned Quantity is less than that ordered quantity (msNavQty < iPaaSLineItemQuantity), identifying a partial return. Rows where either custom field is empty, where the quantity does not parse, or where the returned quantity is not less than the ordered quantity return false and do not proceed. This is what allows an order returned across several shipments to be reflected accurately on its Shopware deliveries.

Description: Updates the return-delivery (return shipping) tracking and status on an existing Shopware order's deliveries as part of an order update.

Mapping Type	Source Field (iPaaS.com)	Destination Field (Shopware)	Description
Field	IsEligibleForUpdateDefaultDelivery	IsEligibleForUpdateDefaultDelivery	recommended — controls whether an existing single (default) delivery is updated in place instead of a new delivery being created.
Dynamic Formula	Line item lookup	LineItemId	recommended — resolves the line a partial-return row applies to from the "Line Item Id" custom field; returns nothing for full-order returns.
Dynamic Formula	Order link lookup	OrderId	required — links the return delivery to the existing Shopware order; if the order is not found the transfer is rejected.
Field	Partial Deliveries	PartialDeliveries	recommended — carries per-package partial-return detail in the format `{quantity}\|{Package}\|{Tracking Code}`, comma-separated for multiple entries.
Field	Shopware Order Delivery Quantity	ShippingCosts_Quantity	optional — sets the quantity component of the return delivery's shipping-cost record.
Field	Cost	ShippingCosts_TotalPrice	optional — sets the total-price component of the return delivery's shipping-cost record.
Field	Cost	ShippingCosts_UnitPrice	optional — sets the unit-price component of the return delivery's shipping-cost record.
Dynamic Formula	Earliest arrival date	ShippingDateEarliest	recommended — uses the "Shopware Earliest Shipping Arrival Date" custom field when present, otherwise a soft default of two days from the transfer date.
Dynamic Formula	Latest arrival date	ShippingDateLatest	recommended — uses the "Shopware Latest Shipping Arrival Date" custom field when present, otherwise a soft default of fourteen days from the transfer date.
Dynamic Formula	Shipping method lookup	ShippingMethodId	recommended — resolves the Shopware shipping method linked through iPaaS.com from a shipping-method name; returns nothing when not found.
Dynamic Formula	Order address lookup	ShippingOrderAddressId	recommended — reads the shipping address already on the linked Shopware order's delivery.
Dynamic Formula	Delivery status from parent order status	StateId	recommended — derives the return-delivery status from the parent order status (Open, Shipped, Shipped (partially), or Cancelled).
Field	TrackingNumber	TrackingNumber	recommended — writes the return shipment tracking number onto the order delivery; the core value this collection delivers.

var returnStatus = "";
if(Parent.Status == "Pending" && !string.IsNullOrEmpty(TrackingNumber)) {
  returnStatus = "Shipped (partially)"
}
else if(Parent.Status == "Complete"){
  returnStatus = "Shipped";
}
else if(Parent.Status == "Cancelled"){
  returnStatus = "Cancelled";
}
else {
  returnStatus = "Open";
}return await GetOrderDeliveryTechnicalNameByStatusName(returnStatus);

The earliest and latest arrival-date defaults (two and fourteen days from the transfer date) are soft defaults; subscribers or their MiSP can adjust the day offsets to match their return expectations. To drive delivery status from this child collection, the Order_Delivery_Status mapping at the order header level should be left null or unmapped, so the two do not compete to set the same status.

Error Handling

Errors surface in Dashboard / Integration Monitoring / Error Logs.

"Transaction can not be created because it does not have valid shopware order id in custom field": thrown by the parent return filter when a return-type transaction has a missing, blank, or non-matching "Shopware Order ID" custom field. Resolution: confirm the originating Shopware order exists and that its id is populated in the iPaaS.com "Shopware Order ID" custom field before transfer.
"This order line sku {Sku} does not exist in Shopware for this order": thrown by the Order Return Lines filter when the line SKU does not resolve to a product-linked order line on the parent's Shopware order. This also occurs when the original order line was added as a custom or manual line item that is not linked to a Shopware product, even when the SKU and a matching product both exist. Resolution: confirm the SKU matches a product-linked order line on that Shopware order; returns for custom or unlinked order lines are not supported (see the Known Limitations article).
Required lookup resolves to nothing (return state, order-line state, product by SKU, or order link not found): the affected record or line is rejected. Resolution: confirm the configured state names exist in the configured language, the product SKU exists in Shopware, and the originating order is linked, then retry the transfer.
Shopware API temporarily unavailable: the transfer fails. Resolution: retry by triggering a new transfer from iPaaS.com once the API is reachable.

Testing & Validation

Test Scenarios

Transfer a return transaction whose "Shopware Order ID" matches an existing Shopware order and confirm a new return is created against that order with the expected state and requested-at timestamp.
Transfer the same return transaction a second time and confirm the existing Shopware return is updated rather than duplicated.
Transfer a return whose "Shopware Order ID" is missing or does not match an existing order and confirm it is rejected with the expected error in the logs.
Transfer a return with multiple returned lines and confirm each line resolves to its Shopware product and order line, is priced from the original order line, and carries the configured line state, quantity, and return reason.
Transfer a return line whose SKU is not an order line on the parent order and confirm it is rejected with the expected SKU error.
Run an order update carrying return tracking with the "Line Item Id" and "Quantity" custom fields populated and a returned quantity less than the ordered quantity; confirm the partial-return delivery is updated with the tracking number, status, shipping method, and arrival dates.
With IsEligibleForUpdateDefaultDelivery true and exactly one delivery on the order, confirm the existing delivery is updated in place rather than a new one created.

Validation Checklist

The configured return-state name and language exist in the target Shopware store.
The configured order-line state name (for example "Returned") exists in the target Shopware store.
Placeholder static values for internal comments and the return reason content/key have been replaced with real values, mapped from source, or a valid ReasonId_Return has been supplied.
The iPaaS.com "Shopware Order ID" custom field is populated on return transactions.
For partial returns, the "Line Item Id" and "Quantity" custom fields are populated on the transferred tracking records.
The order-header-level Order_Delivery_Status mapping is left null or unmapped when delivery status is to be driven by the return-update child.
If the opposite-direction Add/Update Shopware Order Return TO iPaaS.com collection is also enabled, the source of truth for return data is defined and filters are set to prevent circular updates.

Additional Notes

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.

A return is only created against an order, and a return line only against an order line, that already exist in Shopware; records that do not resolve are skipped.
Refund amounts are calculated by Shopware from the original order; custom, partial, or shipping-only refund amounts from iPaaS.com are not applied, and returned lines are priced from the original order line rather than from iPaaS.com.
The return-update child runs only as part of its parent Update Shopware Order FROM iPaaS.com transfer; it cannot be triggered on its own. Partial-delivery handling relies on the Shopware Partial Delivery extension and should be validated in a staging environment before relying on it in production.

Shopware to iPaaS.com Order Mapping Documentation

Shopware to iPaaS.com Order Return Mapping Documentation

Shopware to iPaaS.com Order Deposit Mapping Documentation

Shopware Order Update From iPaaS.com Mapping Documentation

Shopware Order Delivery From iPaaS.com Mapping Documentation