Returns via API

​

Overview

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

​

Prerequisites

• Global-e enables and configures the Return APIs on the Global-e side. Contact your Global-e representative to set up a new third-party integration.
• A Returns Portal — your own, or one of the pre-integrated third-party providers listed below.
• The Global-e Order ID (or Merchant Order ID) and the shopper Email used on the order.
• A ProviderCode that identifies the source of the request.

​

High-level flow

1. Shopper initiates a return, usually using an Order ID and an Email.
2. Shopper selects the return product(s) and the reason(s) for his return.
3. Returns Portal calls GetReturnShippingOptions API to receive a list of available return shipping methods and their associated prices configured on Global-e.
4. 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.
5. Additional refund/credit methods, such as store credit, can be offered to the shopper.
6. 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.
7. Returns Portal shows a confirmation page indicating the return was issued with the documents available for download.
8. 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.
9. Shopper ships the return package using the return documents.
10. 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.)
11. 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

​

Reference

​

Use Cases

​

1. Get the available return shipping options

{
    "ProviderCode": "ExampleProvider",
    "OrderId": "EUQA6215359",
    "Email": "shopper@example.com",
    "ReturnedProducts": [
        {
            "ProductCode": "433117270672",
            "ReturnQuantity": 1
        }
    ]
}

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

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

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

​

GetReturnShippingOptions — Error Codes

​

GetReturnShippingOptions — Product Errors

​

GetReturnDocuments — Error Codes

​

GetReturnDocuments — Product Errors

​

GetReturnDocuments — Model Validation Errors