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

Functional documentation

Global-e Return API’s are designed to provide a comprehensive solution for the return flow.

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 API to receive a list of available return shipping methods and their associated prices configured on Global-e.GetReturnShippingOptions
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.GetReturnDocuments
- 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 Tracking Events 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 APIGetReturnDocuments	Returns with: Single shipping method per country Free shipping cost
ChapsVision	GetReturnDocuments APIGetReturnDocuments	Returns with: Single shipping method per country Free shipping cost
EasyCom	GetReturnDocuments APIGetReturnDocuments	Returns with: Single shipping method per country Free shipping cost
Loop	GetReturnShippingOptions APIGetReturnShippingOptions GetReturnDocuments APIGetReturnDocuments	Exclusive to Shopify Returns with single shipping method per country	Loop/Global-e Integration
ParcelLab	GetReturnDocuments APIGetReturnDocuments	Returns with: Single shipping method per country Free shipping cost

GetReturnShippingOptions (Merchant to Global-e)

The Return Shipping Options 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.

Method/URL

POST https://{globale_api_domain}/Return/GetReturnShippingOptions

Parameters

Request

Parameter Name	Type	Description	Mandatory
`CultureCode`	String	10-character code. Default is EN Maximum: 10 characters.	No
`CurrencyCode`	String	The currency of the return prepaid shipping cost. This is a 3-char ISO currency code. The default should be the same as the origin order currency. If the submitted order currency is not the same as the (outbound) order, apply the currency exchange.	No
`Email`	String	Email that identifies the source of the request.	No
`OrderId`	String	Unique Global-e Order ID or Merchant Order ID. Maximum: 100 characters.	Yes
`ProviderCode`	String	Provider name that identifies the source of the request.	Yes
`ReturnedProducts`	Array of `Products`	The following fields should be populated: `ProductCode` `CartItemID` `ReturnQuantity`	Yes
`ReturnShippingMethodId`	Long	Provides the ID of the return shipping method.	No

Products

Parameter Name	Type	Description	Mandatory
`Attributes`	Object `Attributes`	The attributes of the product. Includes the following fields: AttributeCode Name AttributeTypeCode
`BillingDetails`	Object `BillingDetails`	Provides billing details for the products.
`Brand`	Object `Brand`	The product’s brand. Includes the following fields: BrandCode – string – Up to 50 chars Name – string – Up to 100 chars.	No
`CartItemId`	String	identifier of the cart item on the Merchant’s site. This property may be optionally specified in the SendCart API only so that the same value can be posted back when creating the order on the Merchant’s site with the SendOrderToMerchant API. Max length: 50 chars.	No
`CartItemOptionId`	String	Identifier of the child cart item “option” on the Merchant’s site. This value must be specified if the current cart item is related to a parent item (CartItemId must not be specified for this item because this attribute applies only to the “parent” item itself). For example, this item might indicate a package for the parent item in the same cart. This property may be optionally specified in the SendCart API only so that the same value can be posted back when creating the order on the Merchant’s site with the SendOrderToMerchant API. Max length: 50 chars.	No
`Categories`	Object `Category`	The category of the product. Includes the following: CategoryCode – sting – Up to 50 chars. Name
`DeliveryQuantity`	Decimal	The quantity set for delivery for the product (to be used in the Order APIs described below, as needed).	No
`Description`	String	Description of the Product. Length: Unlimited.	Yes
`DiscountsList`	Object `DiscountsList`	List of possible discounts for products.
`GenericHSCode`	String	The product’s generic HS Code (not country-specific). If specified this property may assist in mapping the product for duties and tax calculation purposes. Max length: 50 chars.	No
`Height`	Decimal	The product’s height in the Merchant’s default unit of length measure (will be converted to CM).	No
`ImageHeight`	Decimal	The product’s image height in pixels	No
`ImageURL`	String	The product’s image URL A JPG formatted image. Max length: 255 chars.	No
`ImageWidth`	Decimal	The product’s image width in pixels	No
`IsBlockedForGlobalE`	Boolean	Indicates if product is available/blocked for international shipping. TRUE - Product is blocked for international shipping. FALSE - Product is available for international shipping.	No
`IsFixedPrice`	Boolean	Indicates if the product’s price is fixed by the Merchant. TRUE - Product’s price is fixed by the Merchant, in the default currency for the country. In this case, all price modifications are disabled for this product. Setting fixed prices is only allowed for the Countries where the `SupportsFixedPrices` flag is set to TRUE. FALSE - Product price is not fixed.	No
`Keywords`	String	The product’s keywords. Length: Unlimited.	No
`Length`	Decimal	The product’s length in the Merchant’s default unit of length measure (will be converted to CM).	No
`ListPrice`	Decimal	Product list price (before discounts) as displayed to the customer, after applying country coefficient, FX conversion, rounding rule (if applicable), and `IncludeVAT` handling.	No
`LocalVATRateType`	Object `VATRateType`	If `UseCountryVAT` for the current Country is TRUE, the `VATRateType` denotes the VAT for the target country. This value must be specified if the order was placed by a local customer. Includes the following fields: `VATRateTypeCode` Rate	No
`OrderedQuantity`	Decimal	Ordered quantity for the product (to be used in Checkout / Order APIs described below, as needed)	No
`OriginalListPrice`	Decimal	Product list price (before any discounts) in the original Merchant’s currency including the local VAT, before applying any price modifications. This property always denotes the product’s price in the default Merchant’s country, regardless of `UseCountryVAT` value for the end customer’s current country.	No
`OriginalSalePrice`	Decimal	Product sale price in the original Merchant’s currency including the local VAT, before applying any price modifications. This property always denotes the product’s price in the default Merchant’s country, regardless of `UseCountryVAT` value for the end customer’s current country.	No
`OriginCountryCode`	String	2-char ISO country code of the product’s country of Origin. The Merchant’s country will be assumed if not specified.	No
`ParentCartItemId`	String	Identifier of the current item’s parent cart item on the Merchant’s site. This value must be specified if the current cart item is related to a parent item (CartItemId must not be specified for this item because this attribute applies only to the “parent” item itself). For example, this item might indicate a custom option (such as a product package) for the parent item in the same cart. This property may be optionally specified in the SendCart API only so that the same value can be posted back when creating the order on the Merchant’s site with the SendOrderToMerchant API. Max length: 50 chars.	No
`ProductCode`	String	SKU code used to identify the product on the Merchant site (to be mapped on the Global-e side). Max length: 100 chars.	Yes
`ProductGroupCode`	String	The product’s group code is on the merchant’s site (to be mapped on the global-e side). Usually, this value is a part of the product SKU code denoting a group of similar products (such as "the same product in different colors"). Max length: 300 chars.	No
`SalePriceBeforeRounding`	Decimal	Product sale price as displayed to the customer, after applying country coefficient, FX conversion, and IncludeVAT handling, before rounding rules have been applied. If not specified, will be deemed equal to SalePrice.	No
`SalePrice`	Decimal	Product sale price as displayed to the customer, after applying country coefficient, FX conversion, rounding rule (if applicable), and IncludeVAT.	No
`ShippingDetails`	Object `ShippingDetails`	Shipping details for the product.
`URL`	String	The product’s information page URL. Max length: 255 chars.	No
`UseCountryVAT`	Boolean	Identifies if the `LocalVATRateType` must be specified. TRUE - Must specify `LocalVATRateType` FALSE - Do not need to set `LocalVATRateType`
`Volume`	Decimal	The product’s volume in the Merchant’s default unit of volume measure (will be converted to cubic CM).	No
`Weight`	Decimal	The product’s weight is in the Merchant’s default unit of weight measure (will be converted to grams). The merchant’s default product weight will be used if not specified	No
`Width`	Decimal	The product’s width is measured in the merchant’s default unit of length (will be converted to CM).	No
`VATRateType`	String	Product’s VAT rate type or class. Max length: 100 chars.	No

Attributes

Parameter Name	Type	Description
`AttributeCode`	String	Custom attribute code denoting a Merchant-specific attribute such as size, color, etc. (to be mapped on the Global‑e side)
`AttributeTypeCode`	String	Code used to identify the attribute type on the Merchant’s site such as “size” for size, “color” for "colour", etc. (to be mapped on the Global‑e side)
`Name`	String	Attribute name

BillingDetails

Parameter Name	Type	Description	Mandatory
`Address1`	String	Address line 1. Length: Unlimited.	No
`Address2`	String	Address line 2. Length: Unlimited.	No
`City`	String	City name. Max length: 500 chars.	No
`CountryCode`	String	2-char ISO country code	No
`CountryName`	String	Country name. Max length: 255 chars.	No
`Email`	String	E-mail address. Max length: 500 chars.	No
`Fax`	String	Fax number. Max length: 250 chars.	No
`FirstName`	String	Customer’s first name. Max length: 40 chars. No length validation. The rest will be truncated.	No
`LastName`	String	Customer’s last name. Max length: 40 chars. No length validation. The rest will be truncated.	No
`MiddleName`	String	Middle name. Max length:40 chars. No length validation. The rest will be truncated.	No
`Phone1`	String	Phone #1. Max length: 250 chars.	No
`Phone2`	String	Phone #2. Max length: 250 chars.	No
`Salutation`	String	Salutation or title (e.g. Dr., Mr., etc.). Max length: 500 chars.	No
`StateCode`	String	State or province ISO code such as AZ for Arizona (if applicable)	No
`StateOrProvince`	String	State or province name. Max length: 500 chars.	No
`UserIdNumber`	String	User’s personal ID document number	No
`UserIdNumberType`	Object `UserIdNumberType`	User’s personal ID document type. Includes the following fields: `UserIdNumberTypeCode` `Name`	No
`UserId`	String	Internal User identifier on the Merchant site	No
`Zip`	String	Zip or postal code. Max length: 250 chars.	No

UserIdNumberType

Parameter Name	Type	Description	Mandatory
`Name`	String	Identification document type name
`UserIdNumberTypeCode`	String	Code denoting a user identification document type (e.g. Passport, ID card, etc.) on the Merchant’s site (to be mapped on the Global‑e side)

Parameter Name	Type	Description	Mandatory
`BrandCode`	String	Brand code on the Merchant’s site (to be mapped on the Global‑e side)
`Name`	String	Brand name

Parameter Name	Type	Description	Mandatory
`CategoryCode`	String	Category code on the Merchant site (to be mapped on the Global‑e side)
`Name`	String	Category name

DiscountsList

Parameter Name	Type	Description	Mandatory
`CouponCode`	String	Merchant `CouponCode` used for this discount (applicable to coupon-based discounts only)	No
`Description`	String	Discount textual description. Length: unlimited.	No
`DiscountCode`	String	Discount code used to identify the discount on the Merchant’s site. This property may be optionally specified in the `SendCart` API only so that the same value can be posted back when creating the order on the Merchant’s site with the `SendOrderToMerchant` API.	No
`DiscountType`	Decimal	One of the following possible values of `DiscountTypeOptions` enumeration denoting a type of discount: Cart discount Shipping discount Loyalty points discount Duties discount Checkout Loyalty points discount Payment charge
`Name`	String	Discount name. Length: unlimited.	Yes
`OriginalDiscountValue`	Currency	Discount value in original Merchant currency including the local VAT, before applying any price modifications. This property always denotes the discount value in the default Merchant’s country, regardless of `UseCountryVAT` for the end customer’s current country. Max length: 18,4.	Yes
`ProductCartItemId`	String	Identifier of the product cart item related to this discount on the Merchant’s site. This property may be optionally specified in the `SendCart` API only so that the same value can be posted back when creating the order on the Merchant’s site with the `SendOrderToMerchant` API. Max length: 50 chars.	No

ShippingDetails

Parameter Name	Type	Description	Mandatory
`Address1`	String	Address line 1. Unlimited length.	No
`Address2`	String	Address line 2. Unlimited length.	No
`City`	String	City name. Max length: 500 chars.	No
`CountryCode`	String	2-char ISO country code	No
`CountryName`	String	Country name. Max length: 255 chars.	No
`Email`	String	E-mail address. Max length: 500 chars.	No
`Fax`	String	Fax number. Max length: 250 chars.	No
`FirstName`	String	First name. Max length: 40 chars. No length validation. The rest will be truncated.	No
`LastName`	String	Last name. Max length:40 chars. No length validation. The rest will be truncated.	No
`MiddleName`	String	Middle name. Max length:40 chars. No length validation. The rest will be truncated.	No
`Phone1`	String	Phone #1. Max length: 250 chars.	No
`Phone2`	String	Phone #2. Max length: 250 chars.	No
`Salutation`	String	Salutation or title (e.g. Dr., Mr., etc.). Max length: 500 chars.	No
`StateCode`	String	State or province ISO code such as AZ for Arizona (if applicable). 2 chars.	No
`StateOrProvince`	String	State or province name. Max length: 500 chars.	No
`UserId`	Decimal	Internal User identifier on the Merchant site	No
`UserIdNumber`	String	User’s personal ID document number	No
`UserIdNumberType`	String	User’s personal ID document type (e.g. Passport, ID card, etc.)	No
`Zip`	String	Zip or postal code. Max length: 250 chars.	No

VATRateType

Parameter Name	Type	Description	Mandatory
`Name`	String	VAT rate type name	No
`Rate`	Decimal	VAT rate decimal value
`VATRateTypeCode`	String	VAT rate type (or class) code on the Merchant’s site (to be mapped on the Global-e side)

Response

Parameter Name	Type	Description	Mandatory
`Cost`	Double	The cost of the shipment	Yes
`Currency`	String	3-letter currency ISO code	Yes
`IsQrLabel`	String	Whether this is a label-free return (QR code only).	No
`isTrackable`	String	Identifies whether this is a trackable return.	Yes
`MerchantOrderId`	String	The unique merchant Order ID. Maximum: 100 characters	Yes
`OrderId`	String	The unique Global-e Order ID. Maximum: 100 characters	Yes
`ReturnShippingDestinationDetails`	Object `ReturnShippingDestinationDetails`	The `ReturnShippingDestinationDetails` object contains all relevant details of the return destination. Contains the following values: `Address` (Mandatory) `City` (Mandatory) `Country` (Mandatory) `Email` (Optional) `Phone` (Optional) `State` or `Province` (Optional) `Zip` (Mandatory)	Yes
`ReturnShippingMethods`	Array of `ReturnShippingMethods`	`ReturnShippingMethods` describes the available return shipping option for the requested items.	Yes
`ShippingMethodDescription`	String	Description of the shipping method.	Yes
`ShippingMethodId`	Integer	The shipping method identifier. Can be used when calling GetReturnDocuments to receive the return document for the selected shipping method.GetReturnDocuments	Yes
`ShippingMethodType`	String	Identifies the shipping method type.	Yes
`ShippingMethodTypeId`	Integer	Possible values: Self-postage (standard) Prepaid Local Prepaid Courier Local Prepaid Consolidated Can be used when calling GetReturnDocuments to receive the return document for the selected shipping method.	Yes
`ShipperName`	String	The name of the shipping service of the return provider	Yes

ReturnShippingDestinationDetails

Field	Type	Description	Mandatory
`Address`	String	Address for return shipping	Yes
`City`	String	City for return shipping	Yes
`Country`	String	Country for return shipping	Yes
`Email`	String	Email for for return shipping	No
`Phone`	String	Phone for return shipping	No
`Province`	String	Province for return shipping	No
`State`	String	State for return shipping	No
`Zip`	String	Zip for return shipping	Yes

ReturnShippingMethods

Parameter Name	Type	Description	Mandatory
`Cost`	Decimal	Shipment cost.
`Currency`	String	Currency used for shipment cost.
`IsQrLabel`	String	Whether this is a label-free return (QR code only).	No
`IsTrackabe`	Boolean	True for supported by Global-e for tracking capabilities and tracking events. False for carriers that Global‑e does not support tracking capabilities
`ReturnShippingTypeId`	Number	Possible values: 1 - Self-postage (standard) 2 - Prepaid 3 - Local Prepaid Courier 4 - Local Prepaid 5 - Consolidated
`ShipperName`	String	Name of the shipper sending the parcel.
`ShippingMethodDescription`	String	A description of the shipment method used to send the parcel.
`ShippingMethodId`	String	The identifier for the shipment method used to send the parcel.
`ShippingMethodType`	String	The shipping method type used to send the parcel.

Errors

General Error Response

{
       "Code": "error code",
       "Error": "error message",
       "Description: "error description"
}

Error Codes

Code	Message
E01	Could not find an available shipping method (No shipping method was found for the submitted products and quantities)
E02	Return is not allowed due to order status %`Order Status`% (Relates to Allowed Return Statuses)
E03	Order ID not found (Returned if the provided OrderId cannot be found for the merchant)
E04	Currency is not valid
E05	There are multiple orders with this `orderID` %`orderID`%
E06	The `ReturnShippingMethodId` %`ReturnShippingMethodId`% is not valid
ME01	Input value for `ProductCode` is not valid
ME02	Input value for `CartItemId` is not valid
ME03	Input value for `ReturnQuantity` is not valid
ME06	Input value for `OrderId` is not valid
ME07	Input value for `Email` is not valid
ME09	Input value for `ReturnedProducts` is not valid
ME10	Input value for `CultureCode` is not valid
ME12	Input value for `CurrencyCode` is not valid
ME13	Input value for `ProviderCode` is not valid
SME15	Input value for `ReturnShippingMethodId` is not valid

Product Errors

Code	Message
PE01	Unable to process this request as the returns period has expired for product %`Product`% (Global-e can enable the PE01 error, and whether to enable validation for expired return periods, through configuration)
PE02	Return product %`Product`% was not found for order
PE03	Product %`Product`% is not returnable
PE04	Requested return product quantity was not delivered to customer %`Customer`%
PE05	Requested return product is virtual ({0})
PE06	Requested return product contains dangerous goods ({0})
PE07	Requested return product quantity is zero ({0})
PE08	OrderProduct was not found for requested return product ({0})
PE09	Child return product was requested without parent product ({0})
PE10	Order product delivery quantity is zero ({0})
PE11	Order product unit sale price is zero ({0})
PE13	Return products collection has duplication
PE14	Return products collection is empty

Examples

Examples

Request

{
     "ProviderCode": "ExampleProvider",
     "OrderId": "EUQA6215359",
     "Email": [email protected],
     "ReturnedProducts": [
         {
             "ProductCode": "433117270672",
             "ReturnQuantity": 1
          }
     ]
 }

Response

{
     "IsSuccess": true,
     "Data": {
         "OrderId": "GE10470948238NL",
         "MerchantOrderId": "EUQA6215359",
         "ReturnShippingMethods": [
             {
                 "ShippingMethodId": 40044878,
                 "ShippingMethodDescription": "DHL-GlobalE",
                 "ShippingMethodType": "Express Courier (Air)",
                 "ShippingMethodTypeID": 2,
	         "ShipperName": "DHL",
                 "IsQrLabel": false,
                 "IsTrackable": true,
                 "Cost": 0.0,
                 "Currency": "EUR"
             }
         ],
         "ReturnShippingDestinationDetails": {
             "Country": "Netherlands",
             "City": "Amsterdam",
             "Address": "Ood 5",
             "Zip": "4751XK",
             "StateOrProvince": "",
             "Email": [email protected],
             "Phone": "310610887191"
         }
     }

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.

Method/URL

POST https://{globale_api_domain}/Return/GetReturnDocuments

Parameters

Request

Field	Type	Description	Mandatory
`CurrencyCode`	String	The currency of the returned prepaid shipping cost. 3-character ISO code.	Mandatory if ShippingCost has a greater value than 0.
`CultureCode`	String	The language for the Return Note document. 3-character ISO code. Currently, English is the only supported language.	No
`Email`	String	The customer's email address. Maximum 100 characters.	No
`IsReturnForService`	Boolean	Indicates if return is created for service	No
`MerchantRMANumber`	String	The Merchant's internal return merchandise authorization (RMA) Number. Maximum 200 characters.	No
`OrderId`	String	Then unique Order ID. Maximum 100 characters.	Yes
`ProviderCode`	String	The provider's name identifies the source of the request.	Yes
`ReturnAddress`	Object `ReturnAddress`	The merchant hub delivery address with return details.	No
`ReturnedProducts`	Array	An array containing the returned products' details. Contains array of ReturnedProduct objects: CartItemID MerchantReturnReasonCode MerchantReturnReasonDescription ProductCode ReturnQuantity	Yes
`ReturnShippingMethodId`	Integer	Based on the end customer's selected shipping method, as returned in the Get Return Shipping Options response. If empty, Global-e uses the cheapest method based on the return shipping type ID (or self-postage if configured)	No
`ReturnShippingTypeId`	Integer	Possible values: Self postage (standard) Prepaid Local Prepaid Courier Local Prepaid Consolidated	No
`ShippingCost`	Decimal	The prepaid shipping cost associated with the return. If not provided, then the ShippingCost will be the configured prepaid/flat return rate.	No

ReturnAddress

Field	Type	Description	Mandatory
Address1	String	Address line 1 for return	Yes
Address2	String	Address line 2 for return	No
City	String	City name for return. Maximum 100 characters.	Yes
CompanyName	String	Company name for return. Maximum 100 characters.	Yes
CountryCode	String	Country code for return, 2-character code	Yes
Email	String	Email address for return. Maximum 500 characters.	No
Fax	String	Fax number for return. Maximum 50 characters.	No
FirstName	String	First name for return. Maximum 500 characters.	Yes
LastName	String	Last name for return. Maximum 500 characters.	No
Phone1	String	Phone 1 for return. Maximum 50 characters.	No
Phone2	String	Phone 2 for return. Maximum 50 characters.	No
PostalCode	String	Postal code for return. Maximum 50 characters.	Yes
StateCode	String	State code for return. Maximum 20 characters.	No
StateOrProvince	String	State or province for return. Maximum 100 characters.	No

ReturnedProduct

Parameter Name	Type	Description	Mandatory
`CartItemId`	String	Identifier of the cart item. Maximum 50 characters.	No
`MerchantReturnReasonCode`	String	The code of the reason for the product return on the merchant. Maximum 100 characters.	No
`MerchantReturnReasonDescription`	String	The description of the reason for the return on the merchant site. Maximum 100 characters.	No
`ProductCode`	String	The ProductCode identifying the product. Maximum 600 characters.	Yes
`ReturnQuantity`	Integer	Quantity of the returned product. Maximum 100 characters.	Yes

Response

When the API call is successful, the call returns the documents required for the return process.

Name	Type	Description
`IsSuccess`	Boolean	True: If the API call is successful. False: If the API call fails.
`Data`	Object `Data`	Data regarding the return, including: GlobalRMANumber (String, Max 100 chars) MerchantOrderId (String, Max 100 chars) MerchantRMANumber (String, Max 100 chars) OrderId (String, Max 100 chars) ReturnDocuments, array containing: DocumentData DocumentTypeCode DocumentTypeName URL ReturnTrackingDetails, array containing: IsQrLabel IsTrackable ShipperName TrackingNumber TrackingURL

Name

Type

Description

IsSuccess

Boolean

True: If the API call is successful.

False: If the API call fails.

Data

Object Data

Data regarding the return, including:

GlobalRMANumber (String, Max 100 chars)
MerchantOrderId (String, Max 100 chars)
MerchantRMANumber (String, Max 100 chars)
OrderId (String, Max 100 chars)
ReturnDocuments, array containing:
- DocumentData
- DocumentTypeCode
- DocumentTypeName
- URL
ReturnTrackingDetails, array containing:
- IsQrLabel
- IsTrackable
- ShipperName
- TrackingNumber
- TrackingURL

Data

Parameter Name	Type	Description
`GlobaleRMANumber`	String	The Global-e return merchandise authorization (RMA) Number. Maximum 100 characters.
`MerchantOrderId`	String	The Merchant Order ID. Maximum 100 characters.
`MerchantRMANumber`	String	The Merchant RMA Number Maximum 100 characters.
`OrderId`	String	The Global-e Order ID. Maximum 100 characters.
`ReturnDocuments`	Object `ReturnDocuments`	Object `ReturnDocuments` provides documents associated with returns. `ReturnDocuments` returns the following documents individually or unified, as a single multi-page document, including: Commercial Invoice (if the electronic invoice is not supported) Shipping Label Return Note
`ReturnTrackingDetails`	Object `ReturnTrackingDetails`	Object `ReturnTrackingDetails` contains tracking details for returns.

ReturnDocuments

The ReturnDocuments returns the following documents individually or unified, as a single multi-page document, including:

Commercial Invoice (if the electronic invoice is not supported)
Shipping Label
Return Note

Parameter Name	Type	Description
`DocumentData`	String	Base64 file type representing the document file content
`DocumentTypeCode`	String	The code value of the document type. This value can be: ShippingLabel ReturnNote CommercialInvoice CombinedReturnDocuments (if UnifiedAllDocumentsUnderOneFile = true) Each document contains the relevant content and with relevant copies. Examples: The return note PDF has only the return note without additional documents. The ReturnCommercialInvoice should have the return commercial invoice with the correct number of copies.
`DocumentTypeName`	String	The name of the document type, e.g. ShippingLabel, ReturnNote or CommercialInvoice (unless the invoice is electronic, no invoice is returned).
`URL`	String	URL of the document

ReturnTrackingDetails

Parameter Name	Type	Description	Mandatory
`IsQrLabel`	String	Identifies whether this is a label-free return (QR code only). This information also applied to the ShippingLabel object	No
`IsTrackable`	String	Identifies whether this is a trackable return	No
`ShipperName`	String	The name of the Shipping Service of the return provider	Yes
`TrackingNumber`	String	Reference number for the tracking service used by the shipper for this return	Yes
`TrackingURL`	String	Tracking URL of the tracking service site used by the shipper	Yes

Errors

Error Codes

Code	Message
E01	Could not create the shipping label. (Note: Not applicable to the self-postage option.)
E02	The return is not allowed due to the order status ({0}) (Global-e can enable the E02 error code and validate the order status through configuration.)
E03	The Order ID was not found
E04	There is already an RMA request for this order ({0})
E07	The return is not allowed due to the parcel status ({0}).
E08	Unable to find the shipping method for the provided return shipping method Id ({0})
E09	The provided `ReturnShippingTypeId` is not valid ({0})
E10	There are multiple orders with this Order ID ({0})
E11	No shipping options were found for the order return ({0})
E12	The return shipping address was not found for order ({0})
E13	Invalid currency code for the provided shipping cost for order ({0})
E14	The return shipping cost cannot be a negative number
E15	The return shipping cost is greater than the return product price
E16	Return address country code is not valid
E17	Return address state code is not valid or does not belong to the country `ReturnAddressStateIsNotValid`
E18	Return address country is not allowed for given order `ReturnAddressCountryIsNotAllowed`
E19	`MerchantRMANumber` is required
E20	`ReturnShippingMethodId` is required for provider ({0})

Product Errors

Code	Message
PE01	Unable to process this request as the returns period has expired for product %`Product`% (Global-e can enable the PE01 error, and whether to enable validation for expired return periods, through configuration)
PE02	Return product %`Product`% was not found for order
PE03	Product %`Product`% is not returnable
PE04	Requested return product quantity was not delivered to customer %`Customer`%
PE05	Requested return product is virtual ({0})
PE06	Requested return product contains dangerous goods ({0})
PE07	Requested return product quantity is zero ({0})
PE08	OrderProduct was not found for requested return product ({0})
PE09	Child return product was requested without parent product ({0})
PE10	Order product delivery quantity is zero ({0})
PE11	Order product unit sale price is zero ({0})
PE13	Return products collection has duplication
PE14	Return products collection is empty

Model Validation Errors

Code	Message
ME01	The input value for `ProductCode` is Invalid
ME02	The input value for `CartItemId` is Invalid
ME03	The input value for `ReturnQuantity` is Invalid
ME04	The input value for `MerchantReturnReasonCode` is Invalid
ME05	The input value for `MerchantReturnReasonDescription` is Invalid
ME06	The input value for `OrderId` is Invalid
ME07	The input value for `Email` is Invalid
ME08	The input value for `ReturnShippingTypeId` is Invalid
ME09	The input value for `ReturnedProducts` is Invalid
ME10	The input value for `CultureCode` is Invalid
ME11	The input value for `MerchantRMANumber` is Invalid
ME12	The input value for `CurrencyCode` is Invalid
ME13	The input value for `ProviderCode` is Invalid
ME14	The input value for `ShippingCost` is Invalid
ME15	The input value for `ReturnShippingMethodId` is Invalid
ME16	"Input value for `ReturnAddress.CompanyName` is required"
ME17	Input value for `ReturnAddress.FirstName` is required
ME19	Input value for `ReturnAddress.City` is required
ME20	Input value for `ReturnAddress.PostalCode` is required
ME21	Input value for `ReturnAddress.CountryCode` is required
ME22	Input value for `ReturnAddress.CompanyName` exceeds the 100-character limit
ME23	Input value for `ReturnAddress.FirstName` exceeds the 500-character limit
ME24	Input value for `ReturnAddress.LastName` exceeds the 500-character limit
ME25	Input value for `ReturnAddress.Email` exceeds the 500-character limit
ME26	Input value for `ReturnAddress.Phone1` exceeds the 50-character limit
ME27	Input value for `ReturnAddress.Phone2` exceeds the 50-character limit
ME28	Input value for `ReturnAddress.Fax` exceeds the 50-character limit
ME29	Input value for `ReturnAddress.City` exceeds the 100-character limit
ME30	Input value for `ReturnAddress.StateOrProvince` exceeds the 100-character limit
ME31	Input value for `ReturnAddress.StateCode` exceeds the 10-character limit
ME32	Input value for `ReturnAddress.PostalCode` exceeds the 50-character limit
ME33	Input value for `ReturnAddress.CountryCode` exceeds the 2-character limit

Examples

Request

curl --location 'https://[globale domain]/Return/GetReturnDocuments' \
 --header 'MerchantGUID: D2ED2A7F-F6ED-4CCB-B611-B44AC8D02250' \
 --header 'Content-Type: application/json' \
 --data-raw '{ "ProviderCode": "Loop",
   "OrderId": "GE314856569TS",
   "Email": "[email protected]",
   "MerchantRMANumber": "RM132",
   "ShippingCost": 10.0,
   "CurrencyCode": "USD",
   "ReturnShippingTypeId": 2,
   "ReturnShippingMethodId": null,
   "ReturnedProducts": [
      {
       "ProductCode": "DKB500680.M8",
       "CartItemId": null,
       "ReturnQuantity": 1,
       "MerchantReturnReasonCode": "",
       "MerchantReturnReasonDescription": "Return Reason from GRD request for product 1"
     },
     {
       "ProductCode": "B7ECS.C8",
       "CartItemId": 1,
       "ReturnQuantity": 1,
       "MerchantReturnReasonCode": "TTT",
       "MerchantReturnReasonDescription": "Return Reason from GRD request for product 2"
     }
   ]
 }'

Responses

Success

{
   "IsSuccess": true,
 "Data": {
    "OrderId": "GE314856569TS", 
        "MerchantOrderId": "314856569",
        "GlobaleRmaNumber": "371104",
        "ReturnTrackingDetails": {
            "TrackingNumber": "1ZXXXXXXXXXXXXXXXX",
            "TrackingURL": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1ZX&requester=ST/",
            "IsQrLabel": "false",
            "IsTrackable": true
        },
        "ReturnDocuments": [
            {
                "DocumentTypeCode": "ShippingLabel",
                "DocumentTypeName": "Shipping Label",
                "DocumentData": "AQCkosNhECNeAACYzH/NIA5NgtHU2QAAAABJRU5ErkJggg==",
                "URL": "https://[MerchantDomain]/url"
            }
        ]
    },
}

Failure

{
        "Code": "error code",
        "Error": "error message",
        "Description: "error description"
        }

Example 1

    "IsSuccess": false,
    "Errors": [
        {
            "Code": "E500",
            "Error": "We encountered an unexpected error and are working to resolve the issue”,
            "Description": null,
            "Success": false
        }
    ]
}

Example 2

{
    "IsSuccess": false,
    "Errors": [
        {
            "Code": "PE27",
            "Error": "Return products collection has duplication",
            "Description": null,
            "Success": false
        },
        {
            "Code": "PE07",
            "Error": "Return product (DKB500680.M8) was not found for order",
            "Description": null,
            "Success": false
        },
        {
            "Code": "PE07",
            "Error": "Return product (B7ECS.C8) was not found for order",
            "Description": null,
            "Success": false
        }
    ]
}

Tracking Events API

Prerequisites

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.

GetTrackingEvents (Merchant to Global-e)

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.

Method/URL:

POST https://{globale_api_domain}/Shipment/GetTrackingEvents

Parameters

Request

Parameter Name	Type	Description	Mandatory
`EventSinceInUTC`	DateTime	Date and time for the earliest time of the order shipment status, UTC, in RFC 2822 format (for example, Fri, 8 Aug 2014 17:13:07 +0000).	No
`OrderIds`	List of Strings	List of Global‑e Order IDs. Up to 100 in each request. Note: each `OrderId`, string, has prefix `GE` followed by numbers, in the format `GE1234`. Max length:100 chars.	One of either `OrderIds` or `TrackingNumbers` are mandatory.
`TrackingNumbers`	List of Strings	List of Global‑e tracking numbers. Up to 100 in each request, with prefix `GE` followed by numbers in the format `GE1234`.	Conditional
`Type`	String	The shipment direction. One of the following: inbound outbound	Yes

Response

Parameter Name	Type	Description	Mandatory
`FailedTrackingNumbers`	List of `FailedTrackingNumbers`	List of objects containing detailed error information. The object includes: `Code` `Description` `Error` `OrderID` `Success`
`SuccessfulTrackingNumbers`	Object `SuccessfulTrackingNumbers`	The events for each `OrderId` are listed in the response. The SuccessfulTrackingNumbers object includes: `GlobaleOrderID` `GlobaleParcelCode` `GlobaleRMANumber (for returns)` `IsTrackingNumberActive` `MerchantOrderID` `MerchantRMANumber (for returns)` `ShipperName` `TrackingEvents` Object. Tracking details for each Global-e order ID in the request, in ascending tracing event time: `GlobaleEventCode` `GlobaleEventDescription` `Location` – Object of `FullAddress` `ShipperEventCode` `ShipperEventDescription` `TrackingEventDateTimeInUTC` `TrackingEventStatus`: One of the following values: DispatchedToCustomer DeliveryAttempt Delivered ReturnedByShipper `TrackingNumber` `TrackingURL` One of the following values: inbound or outbound

FailedTrackingNumbers

Parameter Name	Type	Description
`ErrorInfo`	Object `ErrorInfo`	ErrorInfo object with the error code and error details
`OrderID`	String	Unique order identifier
`Success`	Boolean	Indicates success or failure. True - If the API call is successful. False - If the API call failed.
`TrackingNumber`	String	The Global-e tracking number.

Parameter Name	Type	Description
`Code`	String	The error code
`error`	String	The error message
`Description`	String	The error description

SuccessfulTrackingNumbers

Parameter Name	Type	Description
`GlobaleOrderID`	String	The Global-e order ID for the parcel.
`GlobaleParcelCode`	String	The parcel code used by Global-e.
`GlobaleRMANumber`	String	The Global‑e RMA nnumber.
`IsTrackingNumberActive`	Boolean	Identifies if the tracking number is in use.
`MerchantOrderID`	String	The order ID used by the merchant for the order.
`MerchantRMANumber`	String	The return merchandise authorization number used by the merchant for the parcel.
`ShipperName`	String	The shipping method name.
`TrackingEvents`	Object `TrackingEvents`	Information about order and tracking events.
`TrackingNumber`	String	Global‑e tracking number, with prefix `GE` followed by numbers in the format `GE1234`.
`TrackingURL`	String	Full tracking URL used for this parcel.
`Type`	String	Type of shipment. One of the following values: inbound or outbound

Parameter Name	Type	Description	Mandatory
`TrackingNumber`	String	The tracking number as the shipper has specified

Global-e Tracking Events

The following table lists all the tracking events reported by Global-e:

GlobaleEventCode	GlobaleEventDescription
1	The parcel has been created but is waiting to be manifested (i.e. despatched)
2	The parcel has been manifested (i.e.. despatched)
3	The carrier has yet to receive the parcel into their network
4	The carrier has acknowledged receipt of the parcel into their network
5	The carrier has acknowledged receipt of the parcel into their network but did not receive the required electronic manifest (pre advice file)
6	A collection request has been acknowledged by the carrier
7	The carrier has successfully collected a parcel from a customer
8	The carrier has failed to collect a parcel from a customer
9	The parcel has been misrouted by the carrier due to incorrect routing on the label
10	The parcel has been misrouted by the carrier due to incorrect routing on the label
11	The parcel has been advised as lost within the carriers network
12	The parcel has been delayed due to factors beyond the carriers control (i.e. inclement weather)
13	The parcel is with Customs (NR: This does not necessarily mean that the parcel has been refused entry into the destination country)
14	The parcel has been damaged
15	The parcel is in transit (NB: This could either be en route to a country hubs delivery depot)
16	The parcel has been Left at the local post office for collection
17	The parcel is with a 3rd party sub-contractor and a tracking event has occurred (refer to "Confirmation' field for further information if provided
18	The parcel has left the delivery depot for the recipients address
19	The parcel has been received by a sub-contractor 3rd party
20	The carrier has a query concerning the recipients address (i.e. Unable to locate,. incorrect post code etc.)
21	The carrier has left a calling card for the customer as they were unable to deliver the parcel
22	The carrier has delivered part of the consignment advised (e.g. Parcel 1 parcel of a 2 parcel consignment has been delivered)
23	The parcel is available to collect from the carriers premises
24	The parcel is being held at the delivery depot
25	The recipient no longer resides at the delivery address
26	The recipient refused to take delivery of the parcel
27	The parcel is to be returned to the sender
28	The carrier was unable to deliver the parcel (No reason specified)
29	The parcel has been successfully delivered
30	The carrier has provided some information concerning the parcel
31	An event has occurred after the parcel has been delivered / lost or RTS (i.e._ acknowledgement of a claim)
32	Special delivery instructions to app.?
33	The delivery / collection has requested to be cancelled
34	The carrier has received an electronic pre advice (manifest) for this parcel
35	The parcel has been at a bstatus that does not set an actual or default end date and as such has been 'closed" after a certain period of time dependent on the environment it belongs to
36	The parcel was miss sorted by the carrier and sent to the incorrect -deliver? dept.
37	The recipient has arranged a delivery with the carrier
38	The carrier attempted to deliver the parcel but was unable to access the recipients address to deliver or leave a inning card (i.e. Closed office building, gate-d development etc)
39	The payment for cash on delivery could not be collected
40	The recipient's identification failed
41	The payment could not be processed due to an invalid method of payment by recipient.
42	The payment for cash on delivery of parcel has been collected by the carrier
43	The parcel has been cleared for delivery
44	The parcel has been re boxed / re packed
45	The parcel has been requested to be disposed
46	The declared weight of the parcel does not match the actual weight of the parcel.
47	The parcel has been held by destination Customs
48	The parcel has been held by origin Customs
49	The parcel has been delivered to a neighbour's address
50	The parcel has been delivered to a safe place suggested by the recipient
51	The customer has collected the parcel from the store
52	The parcel is received at store and is ready for collection by recipient_
53	The parcel is ready for collection at the store and it has not been collected after a period of time
54	The parcel has been delivered to a locker or collection point and is ready to be collected by the recipient.
55	The parcel has been delivered to the recipient's preferred point instead of collecting from depot or re-delivery or return
56	The package has been held by the carrier whilst collecting recipient details for clearance
57	The parcel has been re-labelled
58	The parcel attributes lie outside of service capability, i.e. weight/size/remote area issues
59	An SMS has been transmitted to the recipient to inform that the parcel is out for deliver). today
60	An email has been transmitted to the recipient to inform that the parcel is out for delivery today
61	The carrier attempted delivering the parcel but could not deliver
62	The package/s arrived to the destination country
63	A choice that the customer has made for delivery to a safe place (the delivery not happened yet)

Error Codes

Code	Message
E01	The shipment ({0}) is not trackable with this shipper
E02	The order ({0}) is not trackable with this shipper
E03	The provided tracking number ({0}) was not found
E04	The provided order ID ({0}) was not found
E05	The order ({0}) is not associated to the merchant
E06	The tracking number ({0}) is not associated to the merchant
E07	The order ({0}) doesn't have a tracking number
E08	The tracking event type parameter is invalid
E10	The number of input values (Tracking Number and Order IDs) exceeded the ({0}) limit
E11	At least one Order ID or Tracking Number should be specified

Examples

Request

Request for only Global-e orders:

curl --location 'https://[globale domain]/Shipment/GetTrackingEvents' \
 --header 'MerchantGUID: D2ED2A7F-F6ED-4CCB-B611-B44AC8D02250' \ 
{
  "EventSinceInUTC": "2025-04-01T20:08:05Z",
  "Type": "outbound",
  "OrderIds": [
    "GE381652418TS"
],
    "TrackingNumbers":[
]}

Response

{
    "Data": {
        "SuccessfulTrackingNumbers": [
            {
                "GlobaleOrderID": "GE381652418US",
                "MerchantOrderID": "#22165241",
                "GlobaleParcelCode": "null",
                "GlobaleRMANumber": "2832849023948",
                "MerchantRMANumber": "832849932893",
                "IsTrackingNumberActive": true,
                "TrackingNumber": "GE381652418TS2864637A0",
                "Type": "outbound",
                "TrackingUrl": "https://mailingtechnology.com/tracking/?tn=GE381652418TS2864637A0",
                "ShipperName": "Spring XBS Packet Registered-GlobalE",
                "TrackingEvents": [
                    {
                        "ShipperEventDescription": "The parcel has been created but is waiting to be manifested (i.e. despatched)",
                        "TrackingEventDateTimeInUTC": "2024-03-24T09:19:08",
                        "GlobaleEventCode": "1",
                        "GlobaleEventDescription": "The parcel has been created but is waiting to be manifested (i.e. despatched)",
                        "ShipperEventCode": "0",
                        "TrackingEventStatus": [],
                        "Location": {
                            "FullAddress": "BALTIMORE AIRPORT,MD-USA"
                        }
                    }
                ]
            },
            {
                "GlobaleOrderID": "GE8770052418US",
                "MerchantOrderID": "#23816524",
                "GlobaleParcelCode": "null",
                "GlobaleRMANumber": "0239283284948",
                "MerchantRMANumber": "8884994993293",
                "IsTrackingNumberActive": true,
                "TrackingNumber": "GE381652418TS2864637A0",
                "Type": "outbound",
                "TrackingUrl": "https://mailingtechnology.com/tracking/?tn=GE381652418TS2864637A0",
                "ShipperName": "Spring XBS Packet Registered-GlobalE",
                "TrackingEvents": [
                    {
                        "ShipperEventDescription": "The parcel has been created but is waiting to be manifested (i.e. despatched)",
                        "TrackingEventDateTimeInUTC": "2024-03-24T09:19:16",
                        "GlobaleEventCode": "1",
                        "GlobaleEventDescription": "The parcel has been created but is waiting to be manifested (i.e. despatched)",
                        "ShipperEventCode": "0",
                        "TrackingEventStatus": [],
                        "Location": {
                            "FullAddress": "BALTIMORE AIRPORT,MD-USA"
                        }
                    }
                ]
            }
        ],
        "FailedTrackingNumbers": [
           {
            "OrderId": "ABC123",
            "TrackingNumber": "123",
            "ErrorInfo": {
               "Code": "E06",
               "Error": "The tracking number (123) is not associated with the merchant",
               "Description": null
            },
         "Success": false
         }
      ]
    },
    "Errors": null
}

Documentation Portal

Returns via API

Functional documentation

Global-e Return APIs

High-level flow

Integrated Returns Portal

GetReturnShippingOptions (Merchant to Global-e)

Important

Parameters

Products

Attributes

BillingDetails

UserIdNumberType

Brand

Category

DiscountsList

ShippingDetails

VATRateType

ReturnShippingDestinationDetails

ReturnShippingMethods

Errors

Examples

GetReturnDocuments (Merchant to Global-e)

Important

Parameters

ReturnAddress

ReturnedProduct

Data

ReturnDocuments

ReturnTrackingDetails

Errors

Examples

Tracking Events API

Prerequisites

GetTrackingEvents (Merchant to Global-e)

Parameters

FailedTrackingNumbers

ErrorInfo

SuccessfulTrackingNumbers

TrackingEvents

Global-e Tracking Events

Error Codes

Examples

Search results