Implementation

CreateOrderRefund (Merchant to Global-e)

Method/URL

POST https://{globale_api_domain}/Order/CreateOrderRefund

Parameters

OrderRefund

Parameter	Type	Description	Mandatory?
`OrderId`		Global‑e Order id	Mandatory
`FullRefund`	boolean	The refund of the entire order (product, shipping, and taxes).	Optional
`TotalRefundAmount`		The total amount of the order level refund (product and components) in customer currency (taken from the SendOrderToMerchant (Global-e to Merchant) values).	Preferred - Optional
`OriginalTotalRefundAmount`		The total amount of the order level refund (product and components) in merchant currency (taken from the SendOrderToMerchant (Global-e to Merchant) values).	Optional
`ProductsDutiesRefund`	boolean	For products to be refunded also refunds the associated duties to the customer (auto-calculated, thus incompatible with `DutiesAmount`, `TotalRefundAmount` or `OriginalTotalRefundAmount`).	Optional
`ShippingRefund`	boolean	The customer paid refund shipping on the initial order	Optional
`RefundReason`	`OrderRefundReasonObject` (string)	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.	Optional: If the `RefundReason` is not provided, the refund email will be in a generic format, and will not include the product details and image.
`RefundReason`	`OrderRefundReasonObject` (string)	`OrderRefundReasonCode`: Code denoting the order refund reason on the Merchant site (for mapping on the Global‑e side) `Name`: The name of the order refund reason.
`ServiceGestureAmount`		This amount denotes the additional funds to be refunded to the customer on top of the other components in customer currency.	Optional
`ShippingAmount`		This amount denotes the funds to be refunded for shipping costs in customer currency.	Optional
`DutiesAmount`		This amount denotes funds to be refunded for Duties, Taxes, and CCF costs in customer currency.	Optional
`RefundComments`	String	Add comments about the refund,	Optional
`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.
`CustomerPrepaidRefundAmount`	String	The amount deducted from the refund, in the customer's currency.	Optional Must be enabled by Global-e
`OriginalCustomerPrepaidRefundAmount`	String	The amount tdeducted from the refund, in the original/merchant's currency.	Optional Must be enabled by Global-e

RefundProduct list body [array]

Parameter	Description	Mandatory?
`CartItemId`	The unique product line identifier at the order level, as provided in GetCheckoutCartInfo and returned in SendOrderToMerchant (Global-e to Merchant).GetCheckoutCartInfo (to Merchant)
`ProductCode`	The code of the product from the GetOrderDetails endpoint. This can be either the SKU or the `ProductCodeSecondary`.	Mandatory if CartItemId is not specified.
`RefundQuantity`	The product line quantity to refund. If the amount attributes are not specified, a full refund is initiated for (product unit * quantity). For returnable products, use "null" for the refund attribute.	Mandatory if appeasements are not enabled.
`OriginalRefundAmount`	Preferred if not full product amount - The total product line refund amount in Merchant currency, if partial will be backward pro-rated for reconciliation.	Optional
`RefundAmountPercent`	The total product line refund amount, in %.	Optional
`RefundAmount`	If partial, the total product line refund amount in Customer currency will be pro-rated for customer values from transaction amounts. The amount must include domestic VAT, if applicable.	Optional
`OrderRefundReasonObject`* (see previous table)	Provide the product line refund reason for logging on the Global-e side.	Optional
`RefundComments`	Add comments about the refund for logging on the Global‑e side.	Optional

Examples

The following examples are provided for information only and include redundant attribute declarations. Refer to the Use Cases section for examples matching live scenarios.

Parameters: OrderRefund

{
    "OrderId": "GE95135467GB",
    "TotalRefundAmount": "60.95",
    "RefundReason": {
        "OrderRefundReasonCode": 8,
        "Name": "Damaged Item"
    },
    "RefundComments": "Damaged shipment but the customer kept it"
}

Body: RefundProductList with List<RefundProduct>

[{
        "CartItemId": "1381109",
        "RefundQuantity": "1",
        "RefundAmount": "60.95",
        "RefundReason": {
            "OrderRefundReasonCode": 8,
            "Name": "Damaged Item"
        },
        "RefundComments": "Damaged shipment but the customer kept it"
    }
]

Response

If success: OrderRefundInfo

Parameter	Type	Description
NotifyOrderRefund	Merchant.OrderRefund	Notifies the merchant about Global-E initiated refund issued to the end customer.
Reason	String	Text that optionally describes the reason for the Success status
Success	Boolean	Indicates if the respective API method was successful

Merchant.OrderRefund

Parameter	Type	Description
Components	List<Merchant.RefundComponent>	List of `RefundComponent` objects for this order refund
FullRefund	Boolean	The flag indicating that the full refund of the order should be performed (product,shipping,taxes)
MerchantGUID	String	Unique identifier of the Merchant on Global-e
MerchantOrderId	String	Unique order identifier on the Merchant’s site
OrderId	String	Global‑e order unique identifier
OriginalTotalRefundAmount	Decimal	The refund amount in the original Merchant’s currency including the local Merchant’s VAT
Products	List<Merchant.RefundProduct>	List of Refund Product objects for this order refund
RefundAsGiftCard	Boolean	Identifies whether or not the refund was provided as a gift card
RefundComments	String	Comments for the order refund
RefundId	String	Recorded refund id on the Global‑e side
RefundReason	Merchant.OrderRefundReason	Reason for the order refund
ServiceGestureAmount	Decimal	“Service gesture” amount in the customer’s currency is included in TotalRefundAmount.
TotalGiftCardsRefundAmountinMerchantCurrency	Decimal	The total refund amount to the gift card, in the merchant's currency
TotalRefundAmount	Decimal	The total refund amount in the end customer’s currency used for this order’s payment
WebStoreCode	String	Code used on the merchant’s side to identify the web store
WebStoreInstanceCode	String	Code used on the merchant’s side to identify the web store instance where the current cart is originating from

Merchant.RefundProduct

Parameter	Type	Description
CartItemId	String	Identifier of the line item on the Merchant’s site
OriginalRefundAmount	Decimal	Refund the amount in the original Merchant’s currency including the local Merchant’s VAT for this product line item, before applying any price modifications
RefundAmount	Decimal	The refund amount for this product line item in the end customer’s currency used for this order’s payment
RefundComments	String	Comments for this product’s refund
RefundQuantity	Int64	Product quantity
RefundReason	Merchant.OrderRefundReason	Reason for this product’s refund
sku	String	SKU code used to identify the product on the Merchant’s site (to be mapped on the Global‑e side)

Merchant.RefundComponent

Parameter	Type	Description
Amount	Decimal	The refund amount in customer currency
ComponentType	String	Products, Shipping, Duties, PrepaidReturn or ServiceGesture.
IsChargedToMerchant	Decimal	If this component is charged to the merchant, the flag is TRUE (default). If this component is charged to Global-E, the flag is FALSE. If the same component is split between charged to the merchant and charged to Global-E, it should appear twice, each time with a different value in IsChargedToMerchant. Exception is a component PrepaidReturn – it should always be IsChargedToMerchant = TRUE
OriginalAmount	Decimal	The refund amount in merchant currency
RefundAmount	Decimal	The refund amount for this product line item in the end customer’s currency used for this order’s payment

Merchant.OrderRefundReason

Parameter	Type	Description
Name	String	Order refund reason name
OrderRefundReasonCode	Decimal	Code denoting the order refund reason on the Merchant’s site

GiftCardsData

Parameter	Type	Description
BalanceInCustomerCurrency	Decimal	The gift card balance in the customer's currency.
BalanceInGiftCardCurrency	Decimal	The gift card balance in the gift card's currency.
BalanceUsedInCardCurrency	Decimal	The balance used from the gift card in the gift card currency
BalanceUsedInCustomerCurrency	Decimal	The balance used from the gift card in the customer's currency
CardFields	Object	A n object containing the following card details: CardId giftCardBalanceToUse
CardId	Number	Gift card's unique identifier
CustomerCurrencyMode	String	The code for the customer's currency
ErrorCode	String	The error code
ErrorText	String	Text describing the error.
GiftCardCurrencyCode	String	The code for the gift card's currency
IsRefundSuccess	Boolean	Indicates if the refund was successful or not.
GiftCardType	Number	Number indicating the type of gift card
OriginalTotalRefundAmount	Decimal	The refund amount in the original Merchant’s currency including the local Merchant’s VAT
RedeemTransactionId	String	The gift card redemption's transaction identifier.
RefundedBalanceInCustomerCurrency	Decimal	The refunded balance in the customer's selected currency
RefundeBalanceInGiftCardCurrency	Decimal	The refunded balance in the currency of the gift card

If failure: ErrorInfo

Parameter	Type	Description
Code	String	Error code to be returned when an error occurs
Description	String	In case of an error, this property indicates the error message description
Error	String	In case of an error, this property indicates the error message text
Success	Boolean	Indicates if the call has succeeded. FALSE denotes an error or failure

Success response: OrderRefundInfo

{
    "Success": true,
    "Reason": "Refund generated with id 67961",
    "NotifyOrderRefund": {
        "MerchantOrderId": "orderid123",
        "RefundId": "67961",
        "MerchantGUID": "39a4ffdsfds-f6324b-41ce-afdsfa-c8ef18234132",
        "Products": [
            {
                "CartItemId": "2",
                "RefundQuantity": "1",
                "OriginalRefundAmount": "31.2707",
                "RefundAmount": "60.9500",
                "RefundReason": {
                    "OrderRefundReasonCode": null,
                    "Name": "Undefined"
                },
                "RefundComments": "Damaged shipment but the customer kept it"
            }
        ],
        "Components": [
            {
                "Amount": "60.95",
                "OriginalAmount": "31.27",
                "IsChargedToMerchant": "TRUE",
                "ComponentType": "Products"
            }
        ],
        "OrderId": "GE95135467GB",
        "TotalRefundAmount": "60.95",
        "RefundReason": {
            "OrderRefundReasonCode": null,
            "Name": "Undefined"
        },
        "RefundComments": "Damaged shipment but the customer kept it",
        "OriginalTotalRefundAmount": "31.27",
        "ServiceGestureAmount": "0",
        "WebStoreCode": null,
        "WebStoreInstanceCode": "GlobalEDefaultStoreInstance",
        "FullRefund": false
        "TotalGiftCardsRefundAmount": "100.0000",
        "GiftCardsData": {
            "CardId": "1234",
            "BalanceInGiftCardCurrency": 18.3900
            "BalanceInCustomerCurrency": 290.2100,
            "GiftCardCurrencyCode": "EUR"
            "CustomerCurrencyMode": "EUR",
            "BalanceUsedInCardCurrency": 39.0000
            "BalanceUsedInCustomerCurrency": 387.8000,
            "RedeemTransactionId": "1987489732938"
            "CardIdFields": {
               "CardId": "498784937"
               "giftCardBalanceToUse": "100",
              }
         }
    }
}

General API error as ErrorInfo:

{
    "Code": "error code",
     "Error": "error message",
     "Description": "error description"
}

Object processing error as OrderRefundInfo: (Reason is optional)

{
     "Success": false,
     "Reason": "Processing error detail",
     "NotifyOrderRefund": null
}

Documentation Portal

Implementation

CreateOrderRefund (Merchant to Global-e)

Response

Search results