Integration with Shopify’s Return APIs allows seamless communication between Swap and your Shopify order. The integration allows Swap to create a return, refund, and exchange within the original order using Shpoify’s native exchange infrastructure.
Transitioning to the new Returns API integration means a complete alignment of operations between Swap and Shopify. This eliminates the need for accounting reconciliation challenges, improves clarity in sales reports, and increases efficiency and visibility. Using the Exchange API replaces the need to use Swap’s native accounting types.
You can choose to use any of the current accounting types or the exchange API. The current accounting type remains unchanged; enabling it or transitioning back to it is no problem if you have specific needs.
💡 When using the Shopify Returns & Exchange API, all activity remains associated with the original order.
Key Benefits of Using Shopify Returns & Exchange APIs
Full alignment between Shopify and Swap: all return stages will now be documented and visible within Shopify’s original order
Simplified Order Management: Previously, Swap created separate exchange (SW) orders that were not linked to Shopify orders. Now, exchanged items are added to the original order, ensuring accurate restocking and fulfilment tracking.
Improved Reporting Accuracy: Exchanges are now being handled in Shopify’s reporting. Using the Exchange & Returns APIs eliminates financial data discrepancies, removing zero-value accounting issues when refunding exchanges.
Hold Fulfilment: Exchange items are placed “on hold” until fulfilment is triggered. This ensures inventory is reserved but prevents fulfilment until the hold is released. Orders on-hold are excluded from the unfulfilled order list in Shopify. This is not the case if Shopify settings are configured to continue selling through out-of-stock.
Stock Reservation: When an item is “on hold” in Shopify, the stock will be reserved to avoid overselling.
Inventory Management: Returned items are now marked as returned in the original order, finalising the return process. Exchange products are removed from stock adjustments, ensuring accurate inventory tracking. The return status and inventory handling are clearly distinguished.
Refunding & Restocking: Previously, refunds and restocking were linked, requiring items to be restocked at the time of refund. Now, these processes are separate, providing more flexibility.
Return Reason visibility: Return reasons will appear in Shopify according to the mapping configured under “Return reasons” in the dashboard. For information on how to define a return reason, click here.
Exchange Cases
The following information is presented in all cases described below:
Return reason is visible under the return item
Restock note is added and presented under the returned item
Statuses are reflected on the original order itself as well as each item
Equal Exchange
Before processing the exchange:
Exchange item is marked as "on hold.”
Returned item is marked as "Return in progress.”
Both items are documented within the original order.
After processing:
Exchange item is marked as “Unfulfilled.”
Returned item is marked as “Returned.”
Once the exchange is processed, Swap triggers the fulfilment process within Shopify.
No balance is owed by the buyer.
Shopify’s timeline view displays all exchange-related steps, including exchange initiation, hold, 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:
Note: In case required, it is possible to utilise a process so that ‘refund owed’ does not appear, but this solution does not include the Exchanges (including Returns only). For more information, contact customer support through the dashboard.
After processing:
If the exchanged item has a lower value, Shopify will automatically calculate and process the refund when the return is completed.
Exchange item is marked as “Unfulfilled.”
Returned item is marked as “Returned.”
Order is partially refunded.
Sales reports reflects 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:
Exchange item is “on hold.”
Returned item is labeled as “Return in progress.”
Additional payment is required.
After processing:
If the exchange results in a balance due, the amount owed is reflected in the new exchange order.
Swap processes the additional payment, and once collected, the owed balance is marked as paid. In Shopify, the order is marked as ‘paid.’
Sales reports accurately track adjustments.
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 |
Tags Management
Swap will add a tag to mark exchanges and credit on the original order to make sure orders can still be identified using tags to resume current processes relying on this identification
Exchange tags
When an exchange is done on an order in Shopify- Swap will add the same tag that is presented in “SW” orders to the original order
If the order is going through another return with an additional exchange, SWAP will add another tag to recognise that an exchange was already made. This tag will be added once at the 2nd exchange only (only 1 more tag will be added): "Repeated_Exchange."
Credit tag
Swap will add a tag and a note: "Swap credit" on the original order when credit was provided
Same as in exchanges, in cases where credit is requested more than once, another tag will be added to mark that credit was requested before (only 1 more tag will be added): "Repeated_Credit."
Transitioning to Exchange API
If you are transitioning to the Exchange API, there might be several processes that will need to be reviewed to make sure they will work seamlessly with the Exchange API:
Advanced rules based on “SW” orders should be updated to match the new process, as “SW” orders will no longer be created. You can use the order tags presented above to identify what the consumer performed.
In case you have any complementing processes to read the Shopify Sales reports, notice that the reporting will be changed and data might 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 orders involving duties and exchanges, SWAP will process the exchange using the ZeroValue accounting method.
Testing & Enablement
The native exchange flow is available to all merchants upon request.
Swap native exchanges can be toggled on/off for testing purposes. Exchanges submitted after this setting is enabled will adhere to the new flow