Return Methods

GetReturnDocuments

Overview

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.

Important

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

Request

Endpoint URL

POST {globale domain}/Return/GetReturnDocuments

Request Parameters

Field	Type	Mandatory	Description
`ProviderCode`	String	Yes	The Provider's name identifying the source of the request.
`OrderId`	String (100)	Yes	The order unique ID
`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	No	Possible values: `1 -` Returns an appropriate validation error. See Error Codes. `2 - Prepaid` `3 - Local Prepaid Courier` `4 - Local Prepaid`
`ReturnShippingMethodId`	Integer	No	Based on the end customer's selected shipping method, as returned 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 language for the Return Note document. Currently, English is the only supported language.
`ReturnedProducts`	Array	Yes	An array of returned products' details.

ReturnedProducts (Array)

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

Field	Type	Mandatory	Description
`ProductCode`	String (600)	Yes	The `ProductCode` identifying the product
`CartItemId`	Integer	No	Identifier of the cart item
`ReturnQuantity`	Integer	Yes	Quantity of the returned 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 returns the required documents for the return.

If the call fails, it returns ErrorInfo.

Response Parameters

Field	Type	Description
`IsSuccess`	bool	True: If the API call is successful. False: If the API call fails.

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 for the tracking service used by the shipper for this return.
`TrackingURL`	String	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 supported by Global-e for tracking capabilities and tracking events. False for carriers that Global‑e does not support Tracking capabilities

ReturnDocuments (Array)

The 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

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: `ShippingLabel` `ReturnNote` `CommercialInvoice` `CombinedReturnDocuments` (if `UnifiedAllDocumentsUnderOneFile` = true) Each document contains the relevant content and with relevant copies. Examples: The return note PDF has only the return note 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	The error code
`Error`	String	Short error message
`Description`	String	Error description

For the list of errors, see Error Codes

Samples

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

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

Failure Response

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 Codes

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

Product Errors

Error Code	Error Message
PE01	Unable to process this request as the returns period has expired for the product ({0})
PE02	The return product ({0}) was not found for the order
PE03	Product ({0}) is not returnable
PE04	Unable to find the shipping method for the return shipping method id ({0})
PE05	The requested return product quantity was not delivered to the customer ({0})
PE06	The requested return product is virtual ({0})
PE07	The requested return product contains dangerous goods ({0})
PE08	The requested return product quantity is zero ({0})
PE09	The OrderProduct was not found for the requested return product ({0})
PE10	The child return product was requested without the parent product ({0})
PE11	The order product delivery quantity is zero ({0})
PE12	The order product unit sale price is zero ({0})
PE13	The return reason code was not found for the requested product ({0})
PE14	The return product collection has duplications

Model Validation Errors

Error Code	Error Message
ME01	The input value for `ProductCode` is Invalid
ME02	The input value for `CartItemIdInvalid` 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

UpdateRMA

Call the UpdateRMA API to set or update the MerchantRMANumber and send an email to the customer.

SAMPLE

Body:

{
    “OrderId”: ”12345”, (optional)
    “MerchantOrderId”: ”09876”, (optional)
    ”RMANumber”: ”852147”, 
    ”MerchantRMANumber”: ”265646925”
}

URL:

https://{server_name}/Return/UpdateRMA?merchantGUID= F3BE2R-8546-FC38-90SJ-1C780SG8F90SBS

ACCEPTS

UpdateRMANumber updateRMANumber

RETURNS

HttpResponseMessage class

Documentation Portal

Return Methods

GetReturnDocuments

Overview

Important

Request

Request Parameters

ReturnedProducts (Array)

Response

Response Parameters

Data

General API Error as ErrorInfo

Samples

Request

Success Response

Failure Response

Error Codes

UpdateRMA

Search results