> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Refunds via API
> Process customer refunds through Global-e — full or partial, products, shipping, Duties & Taxes, service gestures, and return-shipping deductions — via the CreateOrderRefund API.
## 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
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](/api-reference/create-order-refund)). 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 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.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"FullRefund": true
}
```
```json RefundProductList theme={null}
[]
```
### Full Product Refund
For full product refunds, no refund value is required. Global‑e will establish it from order.
#### Single product
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB"
}
```
```json RefundProductList theme={null}
[
{ "CartItemId": "1381109", "RefundQuantity": 1 }
]
```
#### Multiple Products
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB"
}
```
```json RefundProductList theme={null}
[
{ "CartItemId": "1381109", "RefundQuantity": 2 },
{ "CartItemId": "2371567", "RefundQuantity": 1 }
]
```
### Products with associated duties paid by the customer
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ProductsDutiesRefund": true
}
```
```json RefundProductList theme={null}
[
{ "CartItemId": "1381109", "RefundQuantity": 1 },
{ "CartItemId": "2371567", "RefundQuantity": 1 }
]
```
### Product with shipping
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ShippingRefund": true
}
```
```json RefundProductList theme={null}
[
{ "CartItemId": "1381109", "RefundQuantity": 1 }
]
```
### Shipping Only
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ShippingRefund": true
}
```
```json RefundProductList theme={null}
[]
```
### 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.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"TotalRefundAmount": "320"
}
```
```json RefundProductList theme={null}
[
{ "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.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB"
}
```
```json RefundProductList theme={null}
[
{ "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.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ShippingAmount": "10",
"TotalRefundAmount": "10"
}
```
```json RefundProductList theme={null}
[]
```
#### Service gesture
Example: Customer order placed in Australian dollars. Refunding 50 AUD as a service gesture because of a delay in dispatch.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ServiceGestureAmount": "50",
"TotalRefundAmount": "50"
}
```
```json RefundProductList theme={null}
[]
```
#### Duties Refund
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"DutiesAmount": "60",
"TotalRefundAmount": "60"
}
```
```json RefundProductList theme={null}
[]
```
### 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.
```json OrderRefund theme={null}
{
"OrderId": "GE95135467GB",
"ShippingAmount": "40"
}
```
```json RefundProductList theme={null}
[
{ "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.
```json OrderRefund theme={null}
{
"OrderId": "#4999",
"CustomerPrepaidRefundAmount": 5
}
```
```json RefundProductList theme={null}
[
{ "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](/api-reference/create-order-refund).