Skip to main content

Documentation Portal

Returns via API

Overview

The Get Return Documents API provides essential return information, including return documents and carrier-provided tracking details.

Merchants managing their own return portal or performing returns via a third-party solution can use the Global‑e API to obtain the required return documents and tracking information.

This API involves the following endpoints:

GetReturnDocuments API

Global‑e Return Flow via your Merchant Portal

The following diagram presents the Global‑e Return Flow performed via your Portal.

Returns_Flow.png

The Customer places a return request.

Merchant Flow:

  1. In your Returns Portal Application, select the order, the product, the quantity, and the reason for the return.

  2. Call the GetReturnShippingOptions API to retrieve the Shipping Price from Global‑e.

  3. Calculate the amount of the refund.

  4. Call the GetReturnDocuments API to generate the Merchant RMA Documents.

    Global‑e returns all the required documents as a single PDF file and associated tracking information, if relevant, and lastly creates a Global‑e RMA.

  5. Optional: If relevant, call the Tracking Events API to get all the tracking events for a given tracking number. (Not all returns are trackable).

Optional: Send an email to your Customers.

You can use the standard Global-e functionality for the Refund APIs and Replacements.

For more information, see:

Refunds via API

CreateOrderRefund

CreateOrder

GetReturnShippingOptions

GetShippingDetails API Structure

Use the Returns Shipping Options API to integrate the returns shipping return capability into your returns portal or through a 3rd party returns provider.

The Return Shipping Options API provides essential return information, including a list of return shipping methods and costs. This list can be used with the Overview .

Important

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

Endpoint URL

POST {base_URL_GE}/Return/GetReturnShippingOptions
Parameters

Request

Field

Type

Mandatory

Description

ProviderCode

Yes

Provider name to identify the source of the request.

ProviderCode – the code of the provider (for example, Narvar, Loop etc.)

OrderId

String (100)

Yes

OrderId / Merchant Order Id

CurrencyCode

String (3)

No

The currency of the returned prepaid shipping cost.

The default should be as the origin order currency

If the submitted order currency is different than that of the (outbound) order, apply the currency exchange.

CultureCode

String (10)

No

Default EN

ReturnShippingServiceCode

string

No

Email

string

Yes

ReturnedProducts

array of<Products object>

Each product object has the following fields:

  • ProductCode

  • CartItemID

  • ReturnQuantity

Response

Field

Type

Mandatory

Description

OrderId

String (100)

Yes

Global‑e Order Id

MerchantOrderId

String (100)

Yes

Merchant Order Id

ReturnShippingMethods <array> available return shipping option for the requested items.

ShippingMethodId

Int

Yes

ShippingMethodDescription

string

yes

ShippingMethodType

String

Yes

ShipperName

String

Yes

The shipping service name of the return provider (API Type Name)

IsQrLabel

bool

No

Whether this is a label-free return (QR code only). Only applicable to the ShippingLabel object.

isTrackable

bool

Yes

True for carriers that GE has Tracking events integrations with.

False for carriers for which Global‑e does not support Tracking capabilities.

Cost

double

yes

The cost of the shipment

Currency

String (3)

yes

3-letter currency ISO code

ReturnShippingDestinationDetails (Object)

The ReturnShippingDestinationDetails object contains all relevant details of the return destination.

Field

Type

Mandatory

Description

Country

String

Yes

Inbound ship to country

City

String

Yes

Inbound ship to city

Address

String

Yes

Inbound ship to address

Zip

String

Yes

Inbound ship to zip

State or Province

String

No

Inbound ship to State / province / county

Email

String

no

Phone

String

no

Example

Request 

{
    "ProviderCode": "Narvar",

    "OrderId": "EUQA6215359",

    "Email": [email protected],

    "ReturnedProducts": [

        {

            "ProductCode": "433117270672",

            "ReturnQuantity": 1

         }

    ]
}

Response

{
    "IsSuccess": true,

    "Data": {

        "OrderId": "GE10470948238NL",

        "MerchantOrderId": "EUQA6215359",

        "ReturnShippingMethods": [

            {

                "ShippingMethodId": 40044878,

                "ShippingMethodDescription": "DHL API Express Worldwide Returns-NL-GlobalE",

                "ShippingMethodType": "Express Courier (Air)",

                "ShipperName": "DHL - NL",

                "IsQrLabel": false,

                "IsTrackable": true,

                "Cost": 0.0,

                "Currency": "EUR"

            }

        ],

        "ReturnShippingDestinationDetails": {

            "Country": "Netherlands",

            "City": "Roosendaal (Oud Gastel)",

            "Address": "Cherry 5",

            "Zip": "4751XK",

            "StateOrProvince": "",

            "Email": [email protected],

            "Phone": "310610947191"

        }

    }

Error Code

Error Code

Error 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

The ReturnShippingMethodID is invalid

The submitted ReturnShippingMethodID does not exist or it is invalid.

E06

Return period has expired for the order

Returned if the return period has expired for the provided OrderId.

E07

Return period has expired for ProductCode %ProductCode%

Returned if the product is predefined with a specific return period (per product meta-data).

Note: Returns an array of products if multiple non-returnable products have an expired return date.

E08

ProductCode %ProductCode% is non-returnable product, return is not allowed

Returned if a non-returnable product is selected. Internal GE: Non-returnable features can be found at (Req-2001: Select Items to Return).

Note: Returns an array of products if multiple non-returnable products were selected.

E09

ProductCode %ProductCode% not found in order

Returned if the ProductCode cannot be found for the provided OrderId.

Note: Returns an array of products if there are multiple unrecognized products.

E10

Returned Qty for %ProductCode% is greater than delivered Qty

Returned if the provided quantity is greater than the quantity of the available products to be returned

E11

Returned Qty for %ProductCode% must be greater than 0

Returned if the provided quantity is a negative number

E12

Currency is invalid

The submitted currency is invalid

E15

Shipping service level is not found

Returned if there is no available return shipping option for the provided OrderId and ReturnShippingTypeId

E16

Input value for OrderId is invalid

E17

Input value for MerchantRMANumber is invalid

E18

Input value for CreatedBy is invalid

E19

Input value for ReturnShippingCost is invalid

E20

Input value for ReturnShippingTypeId is invalid

E21

Input value for ProductCode is invalid

E22

Input value for CartItemId is invalid

E23

Input value for ReturnQuantity is invalid

E24

Input value for MerchantReturnReasonCode is invalid

GetReturnDocuments

Overview

Use the GetReturnDocuments API to integrate the return documents capability into your returns portal or through a 3rd party returns provider.

The Return Documents API provides all relevant return documents and 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, Global-e creates a Global-e RMA. Note: Most invoices are electronic and are not returned.

Note: Electronic invoices are not returned.

Important

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

Request

Endpoint URL

POST {globale domain}/Return/GetReturnDocuments
Request Structure

Field

Type

Mandatory

Description

ProviderCode

String

Yes

The Provider's name used to identify the source of the request.

OrderId

String (100)

Yes

OrderId

Email

String (100)

Yes

The customer's email address

MerchantRMANumber

String (200)

No

The Merchant's internal RMA Number

ShippingCost

Decimal

No

The prepaid shipping cost associated with the return.

If not provided, then the ShippingCost will be the configured prepaid/flat return rate.

CurrencyCode

String (3)

Yes (*) See Description

The currency of the returned prepaid shipping cost

(*) Mandatory: Yes, if the ShippingCost parameter is greater than 0.

ReturnShippingTypeId

Integer

Yes

Possible values:

1 - Returns an appropriate validation error. See Error Code.

2 - Prepaid

3 - Local Prepaid Courier

4 - Local Prepaid

ReturnShippingMethodId

Integer

No

Based on the end customer's selected shipping method, as it appears in the Get Return Shipping Options response.

If empty, Global‑e uses the cheapest method based on the return shipping type id.

CultureCode

String (10)

No

The preferred language for the Return Note document.

Currently, English is the only supported language.

ReturnedProducts

Array

Yes

An array of returned product objects

ReturnedProducts

ReturnedProducts (array <ReturnedProducts>) of ReturnedProduct objects for this return.

Field

Type

Mandatory

Description

ProductCode

String (600)

Yes

The ProductCode used to identify the product

CartItemId

Integer

No

Identifier of the cart item

ReturnQuantity

Integer

Yes

Requested quantity to return of the product

MerchantReturnReasonCode

String (100)

No

The code of the reason for the product return on the Merchant site.

MerchantReturnReasonDescription

String (100)

Yes

The description of the reason for the return on the Merchant site

Response

Upon successful API call, the API returns the required documents for the return.

If the API call fails, the API returns ErrorInfo.

Response Structure

Field

Type

Description

IsSuccess

bool

True: If the API call is successful.

False: If the API call fails.

Data

Field

Type

Description

OrderId

String (100)

The Global‑e Order ID

MerchantOrderId

String (100)

The Merchant Order ID

GlobaleRMANumber

String (100)

The Global‑e RMA Number

MerchantRMANumber

String (100)

The Merchant RMA Number

ReturnTrackingDetails (Object)

The ReturnTrackingDetails Object contains the tracking information of the return.

Field

Type

Description

TrackingNumber

String

Reference number valid for the tracking service used by the shipper for this return.

TrackingURL

String

Full tracking URL of the tracking service site used by the shipper.

ShipperName

String

The Shipping service name of the return provider.

IsQrLabel

bool

Optional: Whether this is a label-free return (QR code only).

This is only applicable to the ShippingLabel object.

IsTrackable

bool

True for carriers for which Global-e supports tracking capabilities and tracking events.

False for carriers for which Global‑e does not support Tracking capabilities

ReturnDocuments (Array)

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

  • A Commercial Invoice (if the electronic invoice is not supported)

  • A Shipping Label

  • A Return Note

Field

Type

Description

DocumentData

String

Base64 file type representing the document file content

URL

String

Uri of the document

DocumentTypeCode

String

The code value of the document type. This value can be:

  1. ShippingLabel

  2. ReturnNote

  3. CommercialInvoice

  4. CombinedReturnDocuments (if UnifiedAllDocumentsUnderOneFile = true)

Each document should contain just the relevant content and with relevant copies.

Examples:

The return note PDF should have only the return note in it 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).

General API Error as ErrorInfo

ErrorInfo

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

Structure

Field

Type

Description

Code

String

Error code

Error

String

Error message

Description

String

Error description

For the list of errors, see Error Code

Samples
Request Sample
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",
			"ProductSecondaryCode": "",
			"CartItemId": null,
			"ReturnQuantity": 1,
			"MerchantReturnReasonCode": "",
			"MerchantReturnReasonDescription": "Return Reason from GRD request for product 1"
		},
		{
			"ProductCode": "B7ECS.C8",
			"ProductSecondaryCode": "",
			"CartItemId": 1,
			"ReturnQuantity": 1,
			"MerchantReturnReasonCode": "TTT",
			"MerchantReturnReasonDescription": "Return Reason from GRD request for product 2"
		}
	]
}'
Success Sample
{
    "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"
            }
        ]
    },
    "Errors": null
}
Failure Sample

Example 1

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

Example 2

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

Error Code

Error Message

For more information, see:

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

Allowed Return Statuses

E03

The Order ID was not found

E04

There is already an RMA request for this order ({0})

E05

There are multiple orders with these details ({0})

E06

The return is not allowed due to the parcel status ({0})

Allowed Return Statuses

E07

Unable to find the shipping method for the provided return shipping method Id ({0})

Return Shipping Service Types

E08

The provided ReturnShippingTypeId is not valid ({0})

Return Shipping Service Types

E09

There are multiple orders with this Order ID ({0})

E10

No shipping options were found for the order return ({0})

E11

The return shipping address was not found for order ({0})

E12

Invalid currency code for the provided shipping cost for order ({0})

E13

The return shipping request failed 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

Tracking Events API

Overview

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

For each order the following tracking details are provided:

  • Order ID

  • Tracking Event Time

    • Global-e Event, one or more.

    • Shipper event, one or more.

  • Is the Shipper active?

  • Tracking URL

  • Shipper Name

  • Inbound or Outbound shipping.

  • Location Address – The current location of the order.

  • Tracking Status, one of the following:

    • DispatchedToCustomer

    • DeliveryAttempt

    • Delivered

    • ReturnedByShipper

The list returned in the response is ordered by “Tracking event date time” ASC.

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.

If requesting inbound and outbound tracking events, two different requests should be issued.

Implementation

GetTrackingEvents

API ENDPOINT: GetTrackingEvents

POST request URL: https://{server_name}/Shipment/GetTrackingEvents

Request Parameters

Parameter

Type

Description

Mandatory

EventSinceInUTC

string

Date and time for the earliest time of the order shipment status, UTC time zone, in RFC 2822 format (for example, Fri, 8 Aug 2014 17:13:07 +0000).

No

Type

string

The shipment direction. One of the following

Yes

OrderIds

List of strings

List of Global‑e Order IDs. Up to 100 in each request, in the format GEnnnnnn.

Conditional

TrackingNumbers

List of strings

List of Global‑e tracking numbers. Up to 100 in each request, in the format GEnnnnnn.

Conditional

Response Parameters

Parameter

Type

Description

Mandatory

SuccessfulTrackingNumbers

List of Objects

The events for each OrderId listed in the request. The object includes:

  • GlobaleOrderID

  • MerchantOrderID

  • TrackingNumber

  • Type – Inbound or Outbound

  • ShipperName

  • TrackingEvents Object

TrackingEvents

List of Objects

Tracking details for each Global-e order ID in the request, in ascending tracing event time:

  • ShipmentEventDescription

  • TrackingEventTimeDateUTC

  • GlobaleEventDescription

  • TrackingEventStatus

    One of the following:

    • DispatchedToCustomer

    • DeliveryAttempt

    • Delivered

    • ReturnedByShipper

  • Location – Object of FullAddress

Examples

Request

Request for only for GE orders:

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

Response

{
    "IsSuccess": true,
    "Data": {
        "SuccessfulTrackingNumbers": [
            {
                "GlobaleOrderID": "GE381652418TS",
                "MerchantOrderID": "381652418",
                "GlobaleParcelCode": "240324091851129-P1",
                "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",
                "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",
                "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": []
    },
    "Errors": null
}
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

Allowed statuses for Parcels:

  • Delivered to customer

  • Delivered to store

  • Dispatched

Return Shipping Service Types

Global‑e supports the following Return Shipping Types.

ReturnShippingTypeId

ReturnShippingTypeName

2

Prepaid

3

Local Prepaid Courier

4

Local Prepaid