Refunds via API - Global-e Docs

Overview

The Refund API lets you refund customers through Global-e and entails the following refund use cases:

Full order
Full product
Partial product
Shipping
Duties & Taxes
Service gestures and appeasements
Deduction of return shipping
Any combination of the above

Depending on the use case, refunds can be requested in either merchant or customer currency values, eg. products have a valuation in both currencies when service gestures or duties do not. Customer currency amounts are overall preferred for implementation and allow coverage of all use cases.

Prerequisites

The following system attributes are required:

Global‑e order number (not the ecommerce platform order ID)
Product cartItemId or SKU as specified in the cart shared between Global‑e and the ecommerce platform

Create Order Refund — reference & playground

The orderRefund query parameter, the refundProductsList request body (RefundProduct fields), the OrderRefundInfo response (with Merchant.OrderRefund notification details), the ErrorInfo / ResponseInfo error shapes, examples, and the interactive playground for POST /Order/CreateOrderRefund.

Request

CreateOrderRefund is a mixed request:

orderRefund — the order-level refund details, passed as a URL-encoded, JSON-serialized object in the query string (?orderRefund={…}), not in the body. Its fields are listed below.
refundProductsList — the products to refund, sent as the JSON request body (an array of RefundProduct; its fields render on the reference page). Provide an empty array ([]) for full-order and component-only refunds.

Only orderRefund.OrderId is required.

`orderRefund` object (`OrderRefundDetails`)

Field	Type	Description
`OrderId`	string	Global-e Order id
`FullRefund`	boolean	The refund of the entire order (product, shipping, and taxes).
`TotalRefundAmount`	string	The total amount of the order level refund (product and components) in customer currency (taken from the SendOrderToMerchant (Global-e to Merchant) values).
`OriginalTotalRefundAmount`	string	The total amount of the order level refund (product and components) in merchant currency (taken from the SendOrderToMerchant (Global-e to Merchant) values).
`ProductsDutiesRefund`	boolean	For products to be refunded also refunds the associated duties to the customer (auto-calculated, thus incompatible with DutiesAmount, TotalRefundAmount or OriginalTotalRefundAmount).
`ShippingRefund`	boolean	The customer paid refund shipping on the initial order
`RefundReason`	object	Add the reason for the refund of the order level (for logging on to the Global-e side). Requires mapping on the Global-e side. If the RefundReason is not provided, the refund email will be in a generic format, and will not include the product details and image. Fields: `OrderRefundReasonCode`, `Name`.
`ServiceGestureAmount`	string	This amount denotes the additional funds to be refunded to the customer on top of the other components in customer currency.
`ShippingAmount`	string	This amount denotes the funds to be refunded for shipping costs in customer currency.
`DutiesAmount`	string	This amount denotes funds to be refunded for Duties, Taxes, and CCF costs in customer currency.
`RefundComments`	string	Add comments about the refund.
`externalReference`	string	Optional. If the externalReference is provided upon successful refund creation, it will be saved in the OrderRefunds table and included in the Refunds Components report. Max length: 255.
`ProviderCode`	string	Identifies the return provider that initiated the refund (for example, RGO for ReturnGO). Note: When a recognized provider code is supplied, Global-e sends a refund notification to the merchant. See the introduction for details.
`CustomerPrepaidRefundAmount`	string	The amount deducted from the refund, in the customer’s currency.
`OriginalCustomerPrepaidRefundAmount`	string	The amount deducted from the refund, in the original/merchant’s currency.

Full Refunds and Total Amount Logic

CreateOrderRefund (OrderRefundDetails orderRefund, List<RefundProduct> refundProductsList)

Issues refund for the order specified in orderRefund argument. Optionally may include the list of RefundProducts or components (service gesture, shipping or duties & taxes) to refund for. Lacking Total Refund Amount If orderRefund.TotalRefundAmount is not specified, it will be converted to the end customer’s currency based on RefundAmount or OriginalRefundAmount values for the RefundProducts in refundProductsList and their respective Product VAT rates. For Full Order refunds If orderRefund.FullRefund is specified as true:

A full refund will be created
refundProductsList should not be provided, otherwise, the call will fail with the “Full refund requested but list of RefundProduct is not empty.” error.
orderRefund.TotalRefundAmount and orderRefund.OriginalTotalRefundAmount values (if provided) in the call will be ignored.
Amounts will be recalculated based on the order details.

For Partial Order refunds If product.RefundAmount AND product.OriginalRefundAmount are not specified then:

product.RefundAmount AND product.OriginalRefundAmount will be calculated based on the order products’ price
orderRefund.TotalRefundAmount is recalculated based on the product’s refund amount plus orderRefund.ServiceGestureAmount

For Gift Cards If an order is paid for with gift card (either fully or partially): On the Returns side, Global-e refunds back to the original payment method (such as credit card or APM) first, before the remainder of the refund returns to the gift card. Global-e calculates if there is any amount to return to the gift card, and if so, Global-e will show that refund component in the CreateOrderRefund API.

Merchant Refund Notifications

When the request includes a ProviderCode value, Global-e checks whether that code is recognized as a return provider configured to notify the merchant on refunds. If it is, Global-e automatically sends a refund notification to the merchant after the refund is created. If ProviderCode is omitted, empty, null, or not recognized as a notification-enabled provider, no notification is sent, and the existing behavior is preserved for callers that do not use this parameter.

Refund Input Validation

At least one component must exist in the request (Shipping, Duties, Service Gesture or Products)
If a product was provided, the requested quantity to refund is > 0
Verify that the sum of all requested refund components equals the requested total refund amount
For “Full Refund” requests, the system will verify that no amounts were provided in the request
If a refund was requested in both merchant currency (i.e. Original Currency) and customer currency, the amount provided in the merchant currency will be ignored. The system will recalculate the amount in merchant currency based on the amount provided in the customer currency

Use Cases

Each scenario shows the OrderRefund object (the orderRefund argument) and the RefundProductList (the product array).

Full Order Refund

For full order refunds, no refund value is required. Global‑e will establish it from order. This will include Shipping as well as Duties & Taxes.

OrderRefund

{
    "OrderId": "GE95135467GB",
    "FullRefund": true
}

RefundProductList

[]

Full Product Refund

For full product refunds, no refund value is required. Global‑e will establish it from order.

Single product

OrderRefund

{
    "OrderId": "GE95135467GB"
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": 1 }
]

Multiple Products

OrderRefund

{
    "OrderId": "GE95135467GB"
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": 2 },
    { "CartItemId": "2371567", "RefundQuantity": 1 }
]

Products with associated duties paid by the customer

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ProductsDutiesRefund": true
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": 1 },
    { "CartItemId": "2371567", "RefundQuantity": 1 }
]

Product with shipping

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ShippingRefund": true
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": 1 }
]

Shipping Only

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ShippingRefund": true
}

RefundProductList

[]

Partial Product Refunds

For partial product refunds, a refund value is required. It should be provided:

in customer currency value ideally (“Amount” attributes)
or as percentage
or failing that merchant currency value can be accepted to be reused as a prorated calculation (“OriginalAmount” attributes)

The total amount of refund is expected in parameters if amounts are provided.

Using Customer Currency

Example: Customer order placed in Australian dollars. Refunding 320 AUD of the product value.

OrderRefund

{
    "OrderId": "GE95135467GB",
    "TotalRefundAmount": "320"
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": null, "RefundAmount": "320" }
]

Using Percentage

Example: Customer order placed in Australian dollars. Refunding 50% of product value for a product not being returned.

OrderRefund

{
    "OrderId": "GE95135467GB"
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": null, "RefundAmountPercent": "50" }
]

Components Refunds

For components refunds, customer currency value is required. The total amount of refund is expected in the parameters for input control.

Shipping Refund

Example: Customer order placed in Australian dollars. Refunding 10 AUD for shipping cost.

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ShippingAmount": "10",
    "TotalRefundAmount": "10"
}

RefundProductList

[]

Service gesture

Example: Customer order placed in Australian dollars. Refunding 50 AUD as a service gesture because of a delay in dispatch.

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ServiceGestureAmount": "50",
    "TotalRefundAmount": "50"
}

RefundProductList

[]

Duties Refund

OrderRefund

{
    "OrderId": "GE95135467GB",
    "DutiesAmount": "60",
    "TotalRefundAmount": "60"
}

RefundProductList

[]

Product Return Refund with Shipping

In such a scenario, the Duties&Taxes would not necessarily be expected to be refunded, in which the refund must not be triggered as a full order refund (which would include D&T). Example order for these sections goes as follows:

1 product at 500 CNY
Shipping at 40 CNY
Pre-paid duties of 60 CNY
Item is refunded in full thus amount is not required, only for shipping.

OrderRefund

{
    "OrderId": "GE95135467GB",
    "ShippingAmount": "40"
}

RefundProductList

[
    { "CartItemId": "1381109", "RefundQuantity": 2 }
]

Deduction of Return Shipping

Example: A German shopper is returning an item to a US merchant. The return shipping cost is €5.00 so the merchant deducts €5.00 from the refund.

OrderRefund

{
    "OrderId": "#4999",
    "CustomerPrepaidRefundAmount": 5
}

RefundProductList

[
    { "CartItemId": "12935475658836", "RefundQuantity": "1", "RefundComments": "02-Wrong Product" }
]

Error Codes Reference

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

Generic Validation Errors

#	Context	HTTP status	ErrorInfo
1	Validation – refundProductsList is not null or empty	400	`{ Code = "NullParameter", Error = string.Format("Parameter {0} was null", parameterName), Description = string.Format("Please provide a valid value for the {0} parameter", parameterName) }`
2	Validation – orderRefundObj is not null	400	`{ Code = "NullParameter", Error = string.Format("Parameter {0} was null", parameterName), Description = string.Format("Please provide a valid value for the {0} parameter", parameterName) }`
3	Validation – orderId is not null	400	`{ Code = "NullParameter", Error = string.Format("Parameter {0} was null", parameterName), Description = string.Format("Please provide a valid value for the {0} parameter", parameterName) }`
4	Validation – Multiple refunds	400	`{Code = "MULTI_REFUND_DISALLOWED", Error = "Multiple refund requests are disallowed for this order and reason", Description = "This refund request is rejected because multiple refunds are disallowed for the same order and the same reason code"}`

For the validations below, we do not return an ErrorInfo object but a different object – ResponseInfo.

#	Context	HTTP status	ResponseInfo
1	Validation – Order was not found	400	`{ Success = false, Reason = string.Format("Order {0} could not be found"}`
2	Validation – The order does not belong to the merchant	400	`{ Success = false, Reason = string.Format("Order {0} doesn't belong to this merchant", order.OrderId) }`

The full request and response classes, with success and failure examples, are rendered on the API Reference page.

​Overview

​Prerequisites

Create Order Refund — reference & playground

​Request

​orderRefund object (OrderRefundDetails)

​Full Refunds and Total Amount Logic

​Merchant Refund Notifications

​Refund Input Validation

​Use Cases

​Full Order Refund

​Full Product Refund

​Single product

​Multiple Products

​Products with associated duties paid by the customer

​Product with shipping

​Shipping Only

​Partial Product Refunds

​Using Customer Currency

​Using Percentage

​Components Refunds

​Shipping Refund

​Service gesture

​Duties Refund

​Product Return Refund with Shipping

​Deduction of Return Shipping

​Error Codes Reference

​Generic Validation Errors

Overview

Prerequisites

Request

`orderRefund` object (`OrderRefundDetails`)

Full Refunds and Total Amount Logic

Merchant Refund Notifications

Refund Input Validation

Use Cases

Full Order Refund

Full Product Refund

Single product

Multiple Products

Products with associated duties paid by the customer

Product with shipping

Shipping Only

Partial Product Refunds

Using Customer Currency

Using Percentage

Components Refunds

Shipping Refund

Service gesture

Duties Refund

Product Return Refund with Shipping

Deduction of Return Shipping

Error Codes Reference

Generic Validation Errors