Returns via API

As part of Global-e's comprehensive solution, Global-e delivers a Returns Portal branded with the merchant logo and theme as well as a unique URL to access your Returns Portal.

Merchants who have their own returns portal and third-party return portals can use Global-e Return APIs to integrate functionality for Global-e return shipping options, as well as to obtain required return documents and manage tracking information.

For further information, please consult the pre-integrated third party returns providers list.

For a new third-party integration please contact your representative at Global-e.

Global-e Return APIs

GetReturnShippingOptions API - Used to receive a list of return shipping methods available for a specific order and its associated costs.
GetReturnDocuments API - Used to receive return documents and related information, including the label, the tracking number, the tracking URL, the shipper’s name, the commercial invoice (if relevant), the RMA number, and the return note.
GetTrackingEvents API - Used to receive status events on the delivery status of an order/return.

High-level flow

Following is the recommended high-level workflow for the product(s) return process.

Shopper initiates a return, usually using an Order ID and an Email.
Shopper selects the return product(s) and the reason(s) for his return.
Returns Portal calls GetReturnShippingOptions AAPI to receive a list of available return shipping methods and their associated prices configured on Global-e.
Returns Portal displays the available return shipping methods.
- The return shipping price received from Global-e via the API can be overridden by the Returns Portal.
- Additional refund\credit methods, such as store credit, can be offered to the shopper.
Once the shopper selects the desired return shipping method, the Returns Portal calls GetReturnDocuments API to generate a Global-e RMA and receive all the required return documents.
- Global-e returns all the required documents as a single PDF file including tracking information, if relevant.
Returns Portal shows a confirmation page indicating the return was issued with the documents available for download.
Global-e sends an RMA email - a return request confirmation email - to the shopper with the relevant documents attached.
- The RMA email can be disabled on the Global-e side and managed by the Returns Portal. To disable it please refer to your Global-e representative.
Shopper ships the return package using the return documents.
Optional: the Returns Portal calls the GetTrackingEvents API to get all the tracking events for a given tracking number. (Not all returns are trackable)
Based on the merchant policy, the shopper should be refunded for the returned items (after shipping cost deduction). The merchant portal can use standard Global-e functionality with web portal, pre-integrated webhooks, or Refund APIs.

Integrated Returns Portal

Following is a list of pre-integrated third party returns providers.

Returns Provider	Integrated APIs	Supported Functionalities	Further Information
BabackVision	GetReturnDocuments API	Returns with: Single shipping method per country Free shipping cost
ChapsVision	GetReturnDocuments API	Returns with: Single shipping method per country Free shipping cost
EasyCom	GetReturnDocuments API	Returns with: Single shipping method per country Free shipping cost
Loop	GetReturnShippingOptions API GetReturnDocuments API	Exclusive to Shopify Returns with single shipping method per country	Loop/Global-e Integration
ParcelLab	GetReturnDocuments API	Returns with: Single shipping method per country Free shipping cost

GetReturnShippingOptions (Merchant to Global-e)

The GetReturnShippingOptions API provides essential return information, including a list of return shipping methods and costs.

Important

Global-e must enable and configure this API on the Global-e side.

GetReturnDocuments (Merchant to Global-e)

Use the GetReturnDocuments API to integrate the return documents capability into your Returns Portal or through a third party returns provider.

Important

Global-e enables and configures this API on the Global-e side.

The API provides return documents and related information, including:

The label
The tracking number
The tracking URL
The shipper's name
The commercial invoice (if relevant)
The return merchandise authorization (RMA) number
The return note

In addition, as part of the process, Global-e produces a Global-e RMA.

If so requested by a merchant, Global-e can configure whether to send RMA letters to customers and whether to disable sending RMA information to the merchant. Electronic invoices are not returned.

Tracking Events API

The Get Tracking Events API lets you receive status events on the delivery status of an order. Reporting of tracking events allows both our customers and 3^rd parties to stay informed about the exact location and status of returned items throughout the entire external return journey.

With that, having tracking events for return shipments allows to trigger refunds automatically upon confirmation of returned item receipt (or any other tracking event).

The API accepts one or more order ID numbers, up to 100, on a single call, a list of either orders moved to forward shipments, after checkout completion (outbound), or returns (inbound) and returns their status.

The request can include a list of global-e order IDs, a list of tracking events, or both, but all the same type: Inbound or Outbound. Each request can report on either inbound orders or outbound, but not both. For requesting inbound and outbound tracking events, two different requests should be issued.

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