Integrating Exchange Workflows for Third-Party Return Providers

Introduction

This guide is designed for product and engineering teams at third-party return providers integrating exchange functionality within Shopify for Global-e operated orders. It explains how to implement and support even exchange order flows for Global-e operated orders. Other types of exchange flows are outside the scope of this document.

By following the guidance in this document, return providers can:

Ensure replacement orders are correctly identified and processed as Global-e exchanges.
Deliver a seamless exchange experience to shoppers without triggering refunds, additional charges, or shipping fees.
Understand how responsibilities are divided among the return provider, Shopify, and Global-e.

Supported Exchange Scenario

Global-e supports only even exchanges (variant exchange), meaning:

No refunds or additional charges are permitted.
Shipping fees cannot be collected or refunded.
All shipping costs and any duty or tax adjustments are absorbed by the merchant as part of the service.

Prerequisites

If your exchange flow requires return support for Global-e operated orders, you must integrate with the Global-e Returns APIs. These APIs provide access to the shipping options, labels, and documents needed for handling return flows.

For a complete overview of return integration flows, refer to the Global-e Returns via API documentation.

Exchange Flow

The following figure shows the exchange flow diagram:

To process a Global-e exchange order

Shopper initiates an exchange
The shopper enters their order details in the return provider’s portal. After retrieving order information from Shopify, the return provider verifies whether the order is operated by Global-e.
A Global-e order can be identified by one or more of the following attributes:
- merchant_of_record_app_id: 5806573
- shipping_lines includes {"source": Global-e Carrier Service}
- payment_gateway_names includes Global-e
Item selection
The shopper selects the items to be replaced and provides return reasons within the return provider’s portal.
Return shipping options
The return provider calls the Returns API to retrieve available return shipping options (free shipping or self-postage only). The shopper selects their preferred return method.
Replacement item selection
The shipping option for the exchange order should not be available for shopper selection as it is assigned by Global-e according to the merchant’s configuration and preferences.
Confirm exchange and create RMA
The shopper confirms the exchange in the return provider’s portal. The return provider calls the Returns API to fetch the required return shipping documents. An RMA (Return Merchandise Authorization) is then created, and the return label and shipping instructions are provided to the shopper.
The shopper receives an exchange confirmation and the return documents.
Draft exchange order creation in Shopify
The return provider creates a draft exchange order in Shopify and reserves stock if applicable.
For Global-e to recognize the Shopify exchange order correctly, ensure the following:
- The order must include the OriginalShopifyOrderId field within note_attributes.
- The shipping line should match that of the original order.
- The order must not include a ReplacementForOrder note. This field is automatically populated by Global-e after the replacement order is created.
Example:
```
1 "note_attributes": [
2   {
3     "name": "OriginalShopifyOrderId",
4     "value": "123456789"
5   }
6 ],
7 "shipping_lines": [ {"source": "Global-e Carrier Service"} ]
        
```
It is considered best practice to create the exchange order using the same presentment currency as the original order.
RMA approval
The RMA approval logic for exchange orders is managed by the return provider. On the provider’s side, approval can occur manually (after merchant review), automatically for low-value returns, or based on tracking-event logic.
Global-e provides a Tracking Events API to support tracking-based RMA approval workflows. Once approved, the draft exchange order is converted into a regular Shopify order.
Exchange order processing
The Shopify exchange order is recognized and processed as a Global-e replacement order. When Global-e creates the replacement order, it automatically updates the ReplacementForOrder field. The replacement order is then fulfilled and shipped according to the standard Global-e shipping logic.
The shipping option for the exchange order is assigned by Global-e according to the merchant’s configuration and preferences.

Important Notes

Shopify native exchanges (Shopify Exchanges V2) are not supported via Global-e.
Before integrating, contact your Global-e representative to confirm that the merchant is properly configured in Global-e Admin.
Shipping limitation
- Incoming (return) shipping: For exchanges, only free shipping or self-postage options should be provided.
- Outgoing (replacement) shipping: Only the original shipping method is supported through third-party integrations.
Merchant responsibility: Return providers must inform merchants that Global-e supports only even-value exchanges with free shipping, and that any shipping or duty/tax costs are covered by the merchant.
It is considered best practice to create the exchange orders using the same presentment currency as the original order.
For prepaid shipping rates, shoppers are not charged for return shipping. These costs are reconciled with the merchant as part of the Global-e merchant reconciliation process.

Documentation Portal