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 (see the next section).
This allows you to route items directly back to their original fulfilment location without manually adding the address here.
Automatic routing behaviour
Items assigned to a routing rule will automatically be sent to the correct destination during returns.
Always set a default return address in case a rule cannot determine a specific destination.
3. Define Routing Rules
Navigate to Destinations → Define Routing Rules.
Assign products or product groups to destinations using:
Product tags
Fulfilment locations
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.