Shopify Returns and Exchanges APIs

  • Updated

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.

💡 For Shopify Plus customers: Please make sure the Exchange API feature is enabled:

  1. Click settings
  2. In the organisation section, click on Feature test drives
  3. enable "exchanges"

 

 

Key Benefits of Using Shopify Returns & Exchange APIs

  1. Full alignment between Shopify and SWAP: all return stages will now be documented and visible within Shopify’s original order
  2. 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.
  3. 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.
  4. 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.
  5. Stock Reservation: When an item is “on hold” in Shopify, the stock will be reserved to avoid overselling.
  6. 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.
  7. 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.
  8. 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:

  1. Return reason is visible under the return item
  2. Restock note is added and presented under the returned item
  3. Statuses are reflected on the original order itself as well as each item

 

 

Equal Exchange

Before processing the exchange:

  1. Exchange item is marked as "on hold.”

  2. Returned item is marked as "Return in progress.”

  3. Both items are documented within the original order.

    image (4).png

After processing:

  1. Exchange item is marked as “Unfulfilled.”

  2. Returned item is marked as “Returned.”

  3. Once the exchange is processed, SWAP triggers the fulfilment process within Shopify.

  4. No balance is owed by the buyer.

    Screenshot 2025-01-31 at 11.16.45.png

  5. Shopify’s timeline view displays all exchange-related steps, including exchange initiation, hold, restock, and return reason.

    image (5).png

  6. 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+Refund

Before Processing:

  1. Refund due appears as “refund owed” in Shopify and will appear in Sales reports

    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

  2. The outstanding refund balance represented on the order

    image (6).png

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

After processing:

If the exchanged item has a lower value, Shopify will automatically calculate and process the refund when the return is completed.

  1. Exchange item is marked as “Unfulfilled.”

  2. Returned item is marked as “Returned.”

  3. Order is partially refunded.

    image (7).png

  4. 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 + Additional Payment

Before processing:

  1. Exchange item is “on hold.”

  2. Returned item is labeled as “Return in progress.”

  3. Additional payment is required.

    image (8).png

After processing:

  1. If the exchange results in a balance due, the amount owed is reflected in the new exchange order.

  2. SWAP processes the additional payment, and once collected, the owed balance is marked as paid. In Shopify, the order is marked as ‘paid.’

    Screenshot 2025-01-31 at 12.04.00.png

  3. 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

      image (9).png

    • 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:

  1. 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.
  2. 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. Reach out to customersupport@swap-commerce.com
  • SWAP native exchanges can be toggled on/off for testing purposes. Exchanges submitted after this setting is enabled will adhere to the new flow

Related to

Was this article helpful?

/