Returns via API - Global-e Docs

Overview

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. Global-e Return APIs are designed to provide a comprehensive solution for the return flow:

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.

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

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.
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 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 API	Returns with a single shipping method per country; free shipping cost
ChapsVision	GetReturnDocuments API	Returns with a single shipping method per country; free shipping cost
EasyCom	GetReturnDocuments API	Returns with a single shipping method per country; free shipping cost
Loop	GetReturnShippingOptions API, GetReturnDocuments API	Exclusive to Shopify; returns with a single shipping method per country	Loop/Global-e Integration
ParcelLab	GetReturnDocuments API	Returns with a single shipping method per country; free shipping cost

Reference

Get return shipping options — reference & playground

Request (OrderId, ProviderCode, ReturnedProducts, …), the return shipping methods and costs response, the return destination details, error shapes, examples, and the interactive playground for POST /Return/GetReturnShippingOptions.

Get return documents — reference & playground

Request (OrderId, ReturnedProducts, ReturnAddress, shipping details, …), the RMA + return-documents response, tracking details, error shapes, examples, and the interactive playground for POST /Return/GetReturnDocuments.

The GetReturnShippingOptions page also documents several standard Global-e object definitions (Attributes, BillingDetails, Brand, Category, DiscountsList, ShippingDetails, UserIdNumberType, VATRateType). These are shared, cross-endpoint objects — they are not part of the GetReturnShippingOptions request. See the Shared Objects section of the API reference for their definitions.

Use Cases

A typical portal integration is a two-call flow: first GetReturnShippingOptions to present the available methods and costs, then GetReturnDocuments to generate the RMA and documents for the method the shopper chose.

1. Get the available return shipping options

Request the shipping methods available for the order and the products being returned.

Request

{
    "ProviderCode": "ExampleProvider",
    "OrderId": "EUQA6215359",
    "Email": "shopper@example.com",
    "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": "shopper@example.com",
            "Phone": "310610887191"
        }
    }
}

2. Generate the RMA and return documents

Once the shopper selects a method, call GetReturnDocuments (passing the chosen ReturnShippingMethodId / ReturnShippingTypeId) to generate the Global-e RMA and receive the documents.

Request

{
    "ProviderCode": "Loop",
    "OrderId": "GE314856569TS",
    "Email": "shopper@example.com",
    "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

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

Error Codes

When calling the APIs, the following error codes may be returned.

GetReturnShippingOptions — 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

GetReturnShippingOptions — 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

GetReturnDocuments — 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
`E18`	Return address country is not allowed for given order
`E19`	MerchantRMANumber is required
`E20`	ReturnShippingMethodId is required for provider ({0})

GetReturnDocuments — 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

GetReturnDocuments — 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

​Overview

​High-level flow

​Integrated Returns Portal

​Reference

Get return shipping options — reference & playground

Get return documents — reference & playground

​Use Cases

​1. Get the available return shipping options

​2. Generate the RMA and return documents

​Error Codes

​GetReturnShippingOptions — Error Codes

​GetReturnShippingOptions — Product Errors

​GetReturnDocuments — Error Codes

​GetReturnDocuments — Product Errors

​GetReturnDocuments — Model Validation Errors

Overview

High-level flow

Integrated Returns Portal

Reference

Use Cases

1. Get the available return shipping options

2. Generate the RMA and return documents

Error Codes

GetReturnShippingOptions — Error Codes

GetReturnShippingOptions — Product Errors

GetReturnDocuments — Error Codes

GetReturnDocuments — Product Errors

GetReturnDocuments — Model Validation Errors