Documentation Portal

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 GetReturnDocuments (Merchant to Global-e) .

Method/URL

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

Request

Response

ReturnShippingDestinationDetails (Object)

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

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"

        }

    }

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

The API 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, Global-e creates a Global-e RMA.

Note: Electronic invoices are not returned.

Method/URL

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

Request

Response

If the API call is successful, the Data object returns the documents required for the return. If the call fails, it returns Object FailedTrackingNumbers.

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

Response

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"
            }
        ]
    },
    "Errors": null
}

Failure

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

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.

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

Regarding the API domain, for more details about relevant environments, see Global-e Environments.

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

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
}