The Split Return Shipments feature lets you return items from a single order to multiple destinations. This is useful if items are shipped from different warehouses or regions.
Key Benefits
Multiple Return Addresses: Items can be returned to different locations depending on rules.
Accurate Fulfilment: Ensures returned items go to the right warehouse for processing.
Setting Up Split Shipments
1. Enable Split Shipments
Go to Returns → Shipping → Settings for a carrier.
Toggle Split Shipments to enabled.
Add additional return addresses if needed.
Note: Always set a default return address in case a specific destination cannot be determined.
2. Configure Return Destinations
Return destinations define where items are sent back to during a return.
There are two types of destinations:
Custom Return Addresses
Add any custom warehouse or partner locations manually under Returns → Shipping → Destinations.
These addresses appear in the Return Addresses table and can be edited or removed at any time.
Shopify Fulfilment Locations (for Routing Rules)
Shopify fulfilment locations do not appear in the Return Addresses table.
However, they are automatically available when creating Routing Rules.
This allows you to route items directly back to their original fulfilment location without manually adding the address here.
3. Define Routing Rules
Routing Rules determine where items are sent based on specific conditions.
Navigate to Destinations → Define Routing Rules.
Rules can contain multiple conditions. When multiple conditions are added to a rule, they are evaluated using AND logic, meaning all conditions must match for the rule to apply.
You can assign products or orders to destinations using one or more of the following conditions:
Available Condition Types
Product Vendor
Route items based on the product’s vendor.
Each vendor condition can contain only one vendor.
Vendor-based routing is useful when products from different suppliers must be returned to different warehouses.
Product Tags
Route items based on product tags.
Multiple tags can be used in a rule.
Useful for grouping products across collections or categories.
Fulfilment Location
Route items based on the original Shopify fulfilment location.
This allows returns to go back to the warehouse that fulfilled the order.
Works independently or in combination with other conditions.
Orders Originating from Specific Countries
Route items based on the customer’s country.
Countries are selected using the country selector.
This condition uses the customer’s shipping country.
Can be combined with other conditions for more specific routing.
Example:
Orders fulfilled from Warehouse A → return to Warehouse A
Orders fulfilled from Warehouse A AND customer country is US → return to Warehouse B
Rule Evaluation & Priority
When multiple routing rules could apply to the same item, the system determines which rule to use based on the following order:
1. Specificity First
Rules with more conditions take priority over rules with fewer conditions.
A rule with two conditions (for example, Vendor AND Country) overrides a rule with one condition.
This ensures that more specific routing logic always wins.
2. Condition Type Priority
If two rules contain the same number of conditions, condition types are evaluated in the following order:
Vendor > Tag > Fulfilment Location > Country
Examples:
A rule with one Vendor condition overrides a rule with one Tag condition.
A rule with one Tag condition overrides a rule with one Fulfilment Location condition.
3. Creation Time
If rules are equally specific and contain the same condition types, the rule created first is applied.
4. Customer Portal Flow
Labels for each shipment are generated automatically.
Optional shipping fees can apply per shipment.
5. Managing RMAs in Dashboard
Each RMA splits into packages per destination.
View shipment details, labels, and item assignments for each package.
Instant Exchanges
Instant Exchanges fully support split shipments. When a return contains multiple shipments, each shipment is processed independently. This ensures correct payment handling and prevents issues when different shipments arrive at different times.
How it works
Swap monitors each shipment separately.
When a shipment meets the Instant Exchange conditions (for example, in transit or delivered in time), only the value of the items in that shipment is deducted from the total payment hold.
Other shipments remain unchanged until they meet the conditions.
Once all shipments have arrived, the payment hold is released fully.
Payment adjustments
Returned items trigger payment updates only for the items in their shipment.
The hold amount and payment amount always remain aligned.
The UI and Stripe both update instantly.
A log entry is added for each update, for example:
Shipment 2 is delivered. £40 removed from the total hold amount.
Charge Check Loop for Split Shipments
The charge check loop ensures Instant Exchange calculations stay accurate when shipments arrive at different times.
Monitoring shipment status
Each shipment in the RMA is continuously checked for its status (created, labelled, in transit, delivered).
Hold and payment updates
When one shipment qualifies:
The value of that shipment’s items is removed from the hold amount and the pending payment.
If the hold amount equals the full return value, both the hold and payment decrease together so they are always equal.
If the hold equals 1, only the payment amount changes.
The system does not run calculations after the hold has already been released.
Logs
Every update adds a log to the RMA indicating:
Which shipment changed
Its status
How much was deducted
The updated hold amount
Reminder emails
Reminder emails are still sent if at least one shipment has not met the conditions.
If all shipments meet the conditions, reminder emails are cancelled.
The email amounts always reflect the latest payment calculation.
Customer emails for split shipments
Swap automatically sends customer emails that include all shipments in a return.
When a return contains multiple shipments, the email displays each shipment separately, including:
Carrier
Tracking number
Label download
Items in that shipment
Drop-off and tracking links
Return Delivered email behaviour
The Return Delivered email is sent automatically only if all return labels are created successfully.
If one or more labels fail to generate, the email is not sent automatically from the portal.
You can still send the email manually from the RMA:
Regenerate the labels inside the RMA and resend the email
Or choose to send the email manually, even if not all labels were generated
Example email with multiple shipments
Klaviyo Events & Webhooks
Swap sends complete shipment information to Klaviyo and to all webhook endpoints when split shipments occur. Each shipment is provided separately inside an array.
What webhooks include
Each webhook includes an array of shipments. Every shipment object contains:
shipment_id
order information
carrier information
items included in that shipment
barcode per item
tracking link
return deep link
shipping address
RMA number
This ensures third-party systems (for example, Gorgias and RLM) receive complete data for every shipment without needing to reconstruct packages themselves.
Versioning
Existing webhook versions continue to work.
A new version (v2) supports split shipment arrays.
Merchants can choose the version when creating a webhook.
Fully backwards compatible.
Works whether the RMA has one or multiple shipments.
RMA API Structure for Split Shipments
The RMA API also includes shipments as an array.
Structure (simplified)
{
"rma_id": "rma_123",
"rma_number": "RMA-1001",
"status": "approved",
"shipments": [
{
"shipment_id": "shp_1",
"order": {
"...": "order fields"
},
"carrier": {
"...": "carrier fields"
},
"items": [
{
"rma_item_id": "rma_item_1",
"order_line_id": "12345",
"sku": "TSHIRT-BLACK-S",
"quantity": 1,
"barcode": "0123456789"
}
]
},
{
"shipment_id": "shp_2",
"order": {
"...": "order fields"
},
"carrier": {
"...": "carrier fields"
},
"items": [
{
"rma_item_id": "rma_item_2",
"order_line_id": "12346",
"sku": "HOODIE-GREY-M",
"quantity": 1,
"barcode": "9876543210"
}
]
}
],
"created_at": "2025-11-01T10:00:00Z",
"updated_at": "2025-11-02T12:00:00Z"
}Field names in this example are illustrative. Always refer to the RMA API reference for the exact schema.
Best Practices
Always set a default return address for every carrier.
Verify that all destinations are within carrier coverage.
Configure routing rules carefully to match your workflow.