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 shipment providers 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 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 APIGetReturnShippingOptions - used to receive essential return information, including a list of return shipping methods available for a specific order and associated costs.
GetReturnDocuments APIGetReturnDocuments - 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.

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 price configured on Global-e.GetReturnShippingOptions
Return Portal displays the available return shipping methods, the associated shipping cost and the amount that would be refunded to the shopper after the shipping cost deduction.
- The return shipping price received from Global-e via the API can be overridden by the Returns Portal.
- Additional refund\credit methos, 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\returns portal can use standard Global-e functionality with Refund APIs.

For more information, see:

Refunds via API

CreateOrderRefund

CreateOrder

GetReturnShippingOptions

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 Parameters

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. 3-char ISO currency code. The default should be 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		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>	Each product object has the following fields: `ProductCode` `CartItemID` `ReturnQuantity`	Yes
`ReturnShippingMethodId`	Long	Provides the ID of the return shipping method.	No

Response Parameters

Name	Type	Description	Mandatory
`Cost`	Double	The cost of the shipment	Yes
`Currency`	String	3-letter currency ISO code	Yes
`IsQrLabel`	Boolean	Whether this is a label-free return (QR code only). Only applicable to the `ShippingLabel` object.	No
`isTrackable`	Boolean	True for carriers that Global-ehas Tracking events integrations with. False for carriers for which Global-e does not support Tracking capabilities.	Yes
`MerchantOrderId`	String	Merchant Order Id Maximum: 100 characters	Yes
`OrderId`	String	Global-e Order Id Maximum: 100 characters	Yes
`ReturnShippingDestinationDetails`	Class ReturnShippingDestinationDetails	The `ReturnShippingDestinationDetails` object contains all relevant details of the return destination. Contains the following values: Address (Mandatory) City (Mandatory) Country (Mandatory) Email Phone State or Province Zip
`ReturnShippingMethods`	Array of <ReturnShippingMethods>	`ReturnShippingMethods` describes the available return shipping option for the requested items.
`ShippingMethodDescription`	String		Yes
`ShippingMethodId`	Int	The shipping method identifier. Can be used when calling GetReturnDocuments to receive the return document for the selected shipping method.	Yes
`ShippingMethodType`	String		Yes
`ShipperName`	String	The name of the shipping service of the return provider	Yes

Examples

Request Example

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

Response Example

{
     "IsSuccess": true,
     "Data": {
         "OrderId": "GE10470948238NL",
         "MerchantOrderId": "EUQA6215359",
         "ReturnShippingMethods": [
             {
                 "ShippingMethodId": 40044878,
                 "ShippingMethodDescription": "DHL-GlobalE",
                 "ShippingMethodType": "Express Courier (Air)",
	         "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"
         }
     }

Error Codes

Code	Message	Description
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%	Allowed Return Statuses
E03	Order ID not found	Returned if the provided OrderId cannot be found for the merchant
E04	Currency is invalid
E05	There are multiple orders with this orderID %orderID%
E06	The ReturnShippingMethodId %ReturnShippingMethodId% is invalid
ME01	Input value for ProductCode is invalid
ME02	Input value for CartItemId is invalid
ME03	Input value for ReturnQuantity is invalid
ME06	Input value for OrderId is Invalid
ME07	Input value for Email is invalid
ME09	Input value for ReturnedProducts is invalid
ME10	Input value for CultureCode is invalid
ME12	Input value for CurrencyCode is invalid
ME13	Input value for ProviderCode is invalid
SME15	Input value for ReturnShippingMethodId is invalid
PE01	Unable to process this request as the returns period has expired for product %Product%	Can enable this error code 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

Classes

Data

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	Class ReturnDocuments	Object ReturnDocuments provides documents associated with returns. he 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	Class ReturnTrackingDetails	Object ReturnTrackingDetails contains tracking details for returns.

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 Product Code identifying the product. Maximum 600 characters.	Yes
`ReturnQuantity`	Integer	Quantity of the returned product. Maximum 100 characters.	Yes

GetReturnDocuments

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 name, the commercial invoice (if relevant), the RMA number, and 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 disable sending RMA information to the merchant through configuration on the Global-e side.

Note

Electronic invoices are not returned.

Method/URL

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

Parameters

Request Parameters

Field	Type	Description	Mandatory
`CurrencyCode`	String	The currency of the returned prepaid shipping cost. 3-character ISO code.
`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`	Bool	Indicates if return is created for service	No
`MerchantRMANumber`	String	The Merchant's internal RMA Number. Maximum 200 characters.	No
`Orde`rId	String	The order unique ID. Maximum 100 characters.	Yes
`ProviderCode`	String	The Provider's name identifies the source of the request.	Yes
`ReturnAddress`	ReturnAddress	Merchant hub delivery address with return details.	No
`ReturnedProducts`	Array	An array of returned products' details. Contains array of ReturnedProducts.: 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, Globale 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

Response

Upon successful returns the required documents for the return.

Response Parameters

Name	Type	Description
`IsSuccess`	Boolean	True: If the API call is successful. False: If the API call fails.
`Data`	Class 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

Class 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

Examples

Request Example

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"
     }
   ]
 }'

Response Example

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
        }
    ]
}

Error Codes

Code	Message	More Information
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})	Note: for more information, see Allowed Return Statuses Global-e can configure if to enable the E02 error code and validate the order status.
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}).	Note: for more information, see Allowed Return Statuses.
E08	Unable to find the shipping method for the provided return shipping method Id ({0})	Note: for more information, see Return Shipping Service Types.
E09	The provided ReturnShippingTypeId is not valid ({0})	Note: for more information, see Return Shipping Service Types.
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	More information
PE01	Unable to process this request as the returns period has expired for the product ({0})	Global-e can enable the PE01 error, and whether to enable validation for expired return periods, through configuration.
PE02	The return product ({0}) was not found for the order
PE03	Product ({0}) is not returnable
PE04	The requested return product quantity was not delivered to customer ({0})
PE05	The requested return product is virtual ({0})
PE06	The requested return product contains dangerous goods ({0})
PE07	The requested return product quantity is zero ({0})
PE08	The OrderProduct was not found for the requested return product ({0})
PE09	The child return product was requested without the parent product ({0})
PE10	The order product delivery quantity is zero ({0})
PE11	The order product unit sale price is zero ({0})
PE12	The return reason code was not found for the requested product ({0})
PE13	The return product collection has duplications
PE14	The return product 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

Classes

Products

Parameter Name	Type	Description	Mandatory
`Attributes`	Class Attributes	The attributes of the product. Includes the following fields: AttributeCode Name AttributeTypeCode
`BillingDetails`	Class BillingDetails	Provides billing details for the products.
`Brand`	Class 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`	Class 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`	Class 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`	Bool	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`	Bool	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`	Class 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`	Class Shipping Details	Shipping details for the product.
`URL`	String	The product’s information page URL. Max length: 255 chars.	No
`UseCountryVAT`	Bool	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

Data

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	Class ReturnDocuments	Object ReturnDocuments provides documents associated with returns. he 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	Class ReturnTrackingDetails	Object ReturnTrackingDetails contains tracking details for returns.

SendOrderData

Parameter Name	Type	Description	Mandatory
`Cost`	Decimal	Shipment cost.
`Currency`	Boolean	Currency used for shipment cost.
`IsQrLabel`	Boolean	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 - Returns an appropriate validation error. 2 - Prepaid 3 - Local Prepaid Courier 4 - Local Prepaid
`ShipperName`	Boolean	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.

Allowed Return Statuses

To initiate a return, the order or package must bear one of the specified permissible statuses below.

Return Statuses for Regular Orders (Non-split Orders)

Delivered to customer
Delivered to store
Dispatched to customer
Returned to store

Allowed Return Statuses for Spilt Orders

Delivered to customer
Delivered to store
Dispatched to customer
Returned to Store
Part dispatched (the rest to follow) and payment received.
Part dispatched and part refunded

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

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

Request Parameters

Parameter	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 Parameters

Parameter	Type	Description	Mandatory
`FailedTrackingNumbers`	List<FailedTrackingNumbers>	List of objects containing detailed error information. The object includes: `Code` `Description` `Error` `OrderID` `Success`
`SuccessfulTrackingNumbers`	Class SuccessfulTrackingNumbers	The events for each `OrderId` are listed in the request. 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

Examples

Request

Request for only for GE orders:

{
  "EventSinceInUTC": "2023-01-01 00:04:23",
  "Type": "outbound",
  "OrderIds": [
    "GE381652418TS"
],
    "TrackingNumbers":[
]}

Response

{
    "Data": {
        "SuccessfulTrackingNumbers": [
            {
                "GlobaleOrderID": "GE381652418TS",
                "MerchantOrderID": "381652418",
                "GlobaleParcelCode": "240324091851129-P1",
                "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": null
                        }
                    }
                ]
            },
            {
                "GlobaleOrderID": "GE381652418TS",
                "MerchantOrderID": "381652418",
                "GlobaleParcelCode": "240324091851211-P2",
                "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": null
                        }
                    }
                ]
            },
            {
                "GlobaleOrderID": "GE381652418TS",
                "MerchantOrderID": "381652418",
                "GlobaleParcelCode": "24032409185195-P3",
                "GlobaleRMANumber": "2418039843948",
                "MerchantRMANumber": "4993983832893",
                "GlobaleParcelCode": "24032409185195-P3",
                "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:17",
                        "GlobaleEventCode": "1",
                        "GlobaleEventDescription": "The parcel has been created but is waiting to be manifested (i.e. despatched)",
                        "ShipperEventCode": "0",
                        "TrackingEventStatus": [],
                        "Location": {
                            "FullAddress": null
                        }
                    }
                ]
            }
        ],
        "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
}

Classes

FailedTrackingNumbers

Parameter Name	Type	Description
`ErrorInfo`	Object	ErrorInfo object with the error code and error details
`OrderID`	String	Unique order identifier
`Success`	Bool	Indicates success or failure
`TrackingNumber`	String	The Global-e tracking number.

SendOrderData

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`	Class 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

Documentation Portal

Returns via API

Functional documentation

Global-e Return APIs

High-level flow

GetReturnShippingOptions

Important

Classes

Data

ReturnAddress

ReturnedProduct

GetReturnDocuments

Important

Note

Classes

Products

Data

SendOrderData

Allowed Return Statuses

Return Statuses for Regular Orders (Non-split Orders)

Allowed Return Statuses for Spilt Orders

Tracking Events API

Prerequisites

GetTrackingEvents

Examples

Classes

FailedTrackingNumbers

SendOrderData