This article explains how Swap's integration with Shopify's Returns and Exchange API keeps returns, exchanges, and refunds aligned with your original Shopify orders.
💡 This article applies to Swap's Returns V2 integration with Shopify's Returns and Exchange API.
Swap integrates with Shopify's Returns API to create returns, refunds, and exchanges within the original Shopify order, using Shopify's native exchange infrastructure.
Using this integration brings full alignment between Swap and Shopify: it removes the need for manual accounting reconciliation, improves the accuracy of your sales reports, and increases visibility into return activity across both platforms. Using the Returns and Exchange API replaces the need for Swap's native accounting types.
You can still use any of Swap's accounting types alongside the Returns and Exchange API. Enabling the API, or switching back to an accounting type later, doesn't affect your other settings.
💡 When you use the Shopify Returns and Exchange API, all activity stays associated with the original order.
Key benefits of Swap's Shopify Returns and Exchange API integration
Full alignment between Shopify and Swap: every stage of a return is documented and visible within the original Shopify order.
Simplified order management: exchanged items are added to the original order instead of a separate, unlinked exchange order, keeping restocking and fulfilment tracking accurate.
Improved reporting accuracy: exchanges are handled directly within Shopify's own reporting, removing the zero-value accounting discrepancies that come with refunding exchanges.
Conditional fulfilment holds: Shopify only places an exchange's fulfilment order on hold when the buyer owes an additional balance. An even exchange, or one resulting in a refund, is not held and can be fulfilled straight away. Once that balance is paid, the hold is released and the item becomes fulfillable. Orders on hold are excluded from Shopify's unfulfilled order list, unless your Shopify settings are configured to continue selling out-of-stock items.
Stock reservation: being placed on hold doesn't, by itself, reserve an exchange item's stock. To stop an exchange item being sold to someone else while the return is in progress, enable Enable stock reservation for newly ordered items in your Swap settings — this now works together with the Shopify Exchanges API.
Inventory management: returned items are marked as returned on the original order, and exchanged products are removed from stock adjustments — keeping return status and inventory handling clearly separate.
Flexible refunding and restocking: refunds and restocking are no longer linked, so items don't need to be restocked at the time of refund.
Return reason visibility: return reasons appear in Shopify according to the mapping configured under Return reasons in the Swap dashboard — see how to define a return reason.
Exchange cases
The following applies to every exchange case described below:
The return reason is visible under the returned item.
A restock note is added and shown under the returned item.
Statuses are reflected on the original order itself, and on each item within it.
Equal exchange
Before processing
The returned item is marked Return in progress.
Both items are documented within the original order.
Because no additional balance is owed, Shopify does not place the exchange item on hold — it's available to fulfil straight away.
After processing
The exchange item is marked Unfulfilled.
The returned item is marked Returned.
Swap triggers Shopify's fulfilment process for the exchange item once the exchange is processed.
No balance is owed by the buyer.
Shopify's timeline view displays every exchange-related step, including exchange initiation, restock, and return reason.
Sales report impact: new exchange items are recorded as new sales and contribute to gross sales figures.
Order Name | Adjustment | Sale kind | Product title | Gross sales | Discounts | Returns | Net sales | Taxes | Total sales |
#1268 | No | Order | Blue Silk Tuxedo | 116.660 | 0 | 0 | 116.660 | 23.340 | 140.000 |
#1268 | No | Return | Blue Silk Tuxedo | 0 | 0 | -58.330 | -58.330 | -11.670 | -70.000 |
Summary |
|
|
| £116.66 | £0.00 | -£58.33 | £58.33 | £11.67 | £70.00 |
Exchange and refund
Before processing
If required, it's possible to use a process so that "refund owed" doesn't appear — though this doesn't apply to exchanges, only to returns. For more information, contact Swap customer support through the dashboard.
After processing
If the exchanged item has a lower value, Shopify automatically calculates and processes the refund once the return is completed.
The exchange item is marked Unfulfilled.
The returned item is marked Returned.
The order is partially refunded.
Sales reports reflect the refund amount.
Order Name | Adjustment | Sale kind | Product title | Gross sales | Returns | Net sales | Taxes | Total sales |
#1129 | No | Return | Blue Silk Tuxedo | 0 | -58.340 | -58.340 | -11.660 | -70.000 |
#1129 | No | Order | Red Sports Tee | 41.670 | 0 | 41.670 | 8.330 | 50.000 |
Summary |
|
|
| £41.67 | -£58.34 | -£16.67 | -£3.33 | -£20.00 |
Exchange and additional payment
Before processing
The exchange item is placed on hold, because a balance is due from the buyer.
The returned item is marked Return in progress.
Additional payment is required from the buyer.
After processing
If the exchange results in a balance due, the amount owed is reflected on the new exchange order.
Once Swap collects the additional payment, the balance is marked as paid, and the order is marked Paid in Shopify.
The exchange item's hold is released, so it can be fulfilled.
Sales reports accurately track the adjustment.
Order Name | Adjustment | Sale kind | Product title | Gross sales | Returns | Net sales | Taxes | Total sales |
#1271 | No | Order | Classic Leather Jacket | 66.670 | 0 | 66.670 | 13.330 | 80.000 |
#1271 | No | Return | Blue Silk Tuxedo | 0 | -58.330 | -58.330 | -11.670 | -70.000 |
#1271 | No | Order | Blue Silk Tuxedo | 58.330 | 0 | 58.330 | 11.670 | 70.000 |
Summary |
|
|
| £125.00 | -£58.33 | £66.67 | £13.33 | £80.00 |
Automatic discount for price differences
When a customer makes an equal exchange through the Exchange API, and the replacement item's price has changed since the original purchase, Shopify would otherwise record the item at its current price — even though the customer never paid the difference. Unlike Swap's Zero Value accounting type, the Exchange API doesn't allow an item's price to be edited directly.
To keep the order's recorded value in Shopify accurate:
Swap automatically applies a discount to the exchange item so the recorded value matches what the customer actually paid.
This discount stacks with any other discount already applied to the exchange, such as a carry-over discount or a bonus.
This happens automatically for every store using the Exchange API — there's no setting to turn it on or off.
This keeps Shopify's sales and financial reports accurate, and means refunds calculated from the order use the correct, discounted value.
Tags management
Swap adds a tag to mark exchanges and credit on the original order, so orders can still be identified using tags for any existing processes that rely on this identification.
Exchange tags
When an exchange is made on a Shopify order, Swap adds the same tag used on SW orders to the original order.
If the order goes through another return with an additional exchange, Swap adds a second tag — Repeated_Exchange — to flag that an exchange was already made. This is only added once, at the second exchange.
Credit tag
Swap adds a tag and a note, Swap credit, to the original order when credit is provided.
If credit is requested more than once on the same order, Swap adds a second tag — Repeated_Credit — to flag that credit was requested before. This is only added once, at the second request.
Transitioning to the Exchange API
If you're transitioning to the Exchange API, review the following processes to make sure they continue to work as expected:
Advanced rules based on "SW" orders: update these to match the new process, since "SW" orders are no longer created. Use the order tags described above to identify what the customer did instead.
Shopify sales report integrations: if you have processes that read Shopify's sales reports, be aware that the reporting changes, and data may be presented differently.
Limitations
Shopify does not allow exchanges to be created for certain types of orders, including orders that:
Are older than 2019
Were created by an app other than Swap
Have an invalid billing or shipping address
Include a prepaid subscription
Include duties — for these, Swap processes the exchange using the ZeroValue accounting method
"Refund owed" message and reporting
When using the Shopify Returns API, merchants may see a "Refund owed" message, or a refund entry in Shopify's sales reports, even when no refund has actually been processed. Shopify automatically displays a "You owe the customer a refund" banner during exchange workflows when using the Returns API — this is a standard notification and doesn't mean a refund is genuinely owed. It has no effect on cash flow or automated payment processes.
This behaviour is expected when a return results in a gift card or an exchange, rather than a monetary refund.
Why this happens
When the Returns API is enabled, Swap informs Shopify of the return's state.
Shopify expects a reconciliation on the order (a refund entry) once an item is marked as returned.
If a gift card or exchange is issued instead of a refund, Shopify still registers the transaction as though a refund were expected.
As a result, "Refund owed" may appear on the order page, and Shopify's reports may list it as refunded even though no payment occurred.
This doesn't affect the customer experience or payment flow — it only affects how returns appear in Shopify's reporting.
Impact on Shopify reports
In Shopify's Sales and Net Sales reports, "refund owed" lines can appear as refunded transactions, which may create a discrepancy between Shopify's reports and your actual refund totals.
For a clearer view of your sales data, use Shopify's Total Sales Over Time or Total Sales by Order reports under Finance. These present unedited sales values, including exchanges where no refund was issued.
To display only genuine refunds:
Open any Sales report — for example, Sales over time.
Add the filter: Order payment status → is → Refunded.
This excludes entries where no refund was issued, such as exchanges or gift cards.
Options and workarounds
Best practice for the Shopify Returns API:
Enable it for seamless integration and visibility into Shopify's return workflows.
Disable it if pending refund flags or banners disrupt your operations, or if your business relies heavily on Swap's internal processes instead.
Disabling the API only affects returns processed afterwards — pre-existing orders keep their previous statuses and notifications.
If the refund display is confusing, you can disable the Returns API from within your Shopify admin's Returns settings — this isn't a Swap dashboard setting.
Orders created before disabling will still show "Refund owed."
Orders created afterwards will not.
Alternatively, keep using the Returns API and apply the reporting filter above to maintain accurate financial visibility.
Testing and enablement
The native exchange flow is available to all merchants on request — reach out to Swap customer support.
Swap's native exchanges can be toggled on and off for testing. Exchanges submitted after this setting is enabled follow the new flow.