Refund Methods

CreateOrderRefund (Merchant to Global-e)

The CreateOrderRefund API Issues a refund for the order specified in the orderRefund argument. Optionally, this method may include the list of RefundProducts to refund. If orderRefund.TotalRefundAmount is not specified, it is converted to the end customer’s currency based on the RefundAmount or OriginalRefundAmount values for the RefundProducts in the refundProductsList and their respective Product VAT rates.

If orderRefund.FullRefund is specified as true:

A full refund is created.
refundProductsList should not be provided, otherwise, the call fails with an error "Full refund requested but list of RefundProduct is not empty."
The orderRefund.TotalRefundAmount and orderRefund.OriginalTotalRefundAmount values which are provided in the call are ignored and recalculated based on the order details.

ELSE

If product.RefundAmount AND product.OriginalRefundAmount are not specified then:

product.RefundAmount AND product.OriginalRefundAmount are calculated based on the order product price.
orderRefund.TotalRefundAmount is recalculated based on the products refund amount plus the sum of all non-product related refund components
(orderRefund.ServiceGestureAmount + orderRefund.DutiesAmount + orderRefund.ShippingAmount)

In case a full refund is not performed or the refund request/refund item quantity is not valid, a JSON response is returned in accordance to the Merchant Account Settings ReturnResponseOfErrorInfoStruct value.

If this Merchant Account Settings is true, the JSON response is in the ErrorCode struct.
Otherwise, the response is in the ResponseInfo struct.

The Merchant Account Settings ‘SetAllPrepaidReturnsWithRefund’ supports all prepaid returns includes free by Admin and free by Merchant that the return IDcwill be sent to NotifyOrderRefund and wiil link the OrderRefund with the return.

Method/URL

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

Parameters

Request

Name	Type	Description	Mandatory
`orderRefund`	Object `OrderRefundDetails`	Order refund details for the specified order	Yes
`refundProductsList`	List of `RefundProduct`	List of `RefundProduct` objects for this order refund.	Note that this products list is mandatory if the refund is issued for Products.

OrderRefundDetails

Parameter Name	Type	Description	Mandatory
`CustomerAmountPrepaidRefund`	Decimal	The return shipping cost. Populated by the Merchant.
`CustomerPrepaidRefundAmount`	Decimal	Represents a prepaid fee that the customer is required to pay in case of refunds. This fee is deducted from the total refund amount due to the customer. The value of this field is specified in the currency of the customer.	No
`DutiesAmount`	Decimal	The “`Duties`” amount in the customer's currency included in the `TotalRefundAmount`. “`Duties`” denotes the funds that should be refunded due to Duties, Taxes and CCF costs.	No
`FullRefund`	Boolean	The flag indicates that the full refund of the order should be performed. TRUE provide full refund FALSE do not provide full refund	No
`InitiatedBy`	String	Identifies who initiated the refund process.	No
`OrderId`	String	Global‑e order unique identifier (previously submitted to the Merchant’s `SendOrderToMerchant` method when the order had been created with Global‑e checkout) or Order unique identifier on the Merchant’s site.
`OriginalAmountPrepaidRefund`	Decimal	The return shipping cost in the customer’s currency.
`OriginalCustomerPrepaidRefundAmount`	Decimal	Represents a prepaid fee that the customer is required to pay in case of refunds. This field is populated in the original currency of the Merchant. The prepaid fee is converted to the currency of the customer and then deducted from the total refund amount due to the customer. Currency conversion rates are calculated based on the Spot rate on the day of the order creation. Use this field only when `CustomerPrepaidRefundAmount` is not provided. Make sure that only one of these fields is populated at a time to avoid double deductions.	No
`OriginalTotalRefundAmount`	Decimal	The refund amount in the original Merchant currency including the local Merchant VAT.	No
`ProductsDutiesRefund`	Boolean	The flag indicates that the refund for the products should also include the associated duties and taxes. If `ProductsDutiesRefund` is specified, all refund totals will be auto-calculated, and therefore specifying `DutiesAmount`, `TotalRefundAmount` or `OriginalTotalRefundAmount` will return an error in this case. TRUE - Refund includes taxes. FALSE - Refund will not include taxes.	No
`RefundComments`	String	Merchant's comments for the order refund	No
`RefundReason`	Object `OrderRefundReason`	Reason for the order refund	No
`ServiceGestureAmount`	Decimal	“Service gesture” amount in the customer’s currency included in `TotalRefundAmount`. “Service gesture” denotes any additional refund granted to the user, on top of the refund related to other components.	No
`ShippingAmount`	Decimal	The “`Shipping`” amount in the customer’s currency included in `TotalRefundAmount`. “`Shipping`” denotes the funds that should be refunded due to shipping costs.	No
`ShippingRefund`	Boolean	The flag indicates that the full shipping cost should be refunded. Either the `ShippingRefund` flag or `ShippingAmount` can be provided at the same time If a part of the shipping cost was already refunded – only the remaining available part will be refunded. TRUE - Shipping cost is refunded. FALSE - Shipping cost is not refunded.	No
`TotalRefundAmount`	Decimal	The total refund amount in the end customer’s currency and used for this order’s payment. If this attribute is not specified, `OriginalTotalRefundAmount` along with the sum of `OriginalRefundAmount` values in the `refundProductsList` specified in the respective `CreateOrderRefund`, will be used to calculate the `TotalRefundAmount`.	No

OrderRefundReason

Parameter Name	Type	Description	Mandatory
`Name`	String	Order refund reason name
`OrderRefundReasonCode`	String	Code denoting the order refund reason on the Merchant’s site (to be mapped on the Global‑e side)

RefundProducts

Parameter Name	Type	Description	Mandatory
`CartItemId`	String	Identifier of the line item on the Merchant’s site. This property is mandatory and should be equal to the respective Product’s `CartItemId` originally specified in the `SendCart` method for the order being refunded.	Yes
`OriginalRefundAmount`	Decimal	The refund amount in the original Merchant’s currency including the local Merchant’s VAT for this product line item, before applying any price modifications (i.e. part of or the full value paid by Global-e to the Merchant, as was specified in `Merchant.Product.Price` for the respective order).	No
`ProductCode`	String	Product SKU or Product Variant ID according to Merchant configuration. Can be used as Product Identifier instead of `CartItemId`. In case there are multiple products with the same identifier we will choose one of them arbitrarily.	No
`RefundAmount`	Decimal	The refund amount for this product line item in customer currency and used for this order payment. If this attribute is not specified, `OriginalRefundAmount` multiplied by `RoundingRate` for this product line item should be used to calculate `TotalRefundAmount` for this order’s refund.	Yes
`RefundComments`	String	Merchant's comments for this product’s refund	No
`RefundQuantity`	Decimal	Product quantity (i.e. a part of the originally ordered quantity) that the refund refers to.	Yes
`RefundReason`	Object `OrderRefundReason`	Reason for this product’s refund	No
`Sku`	String	The field is obsolete, please use `ProductCode` instead.	No

OrderRefundReason

Parameter Name	Type	Description	Mandatory
`Name`	String	Order refund reason name
`OrderRefundReasonCode`	String	Code denoting the order refund reason on the Merchant’s site (to be mapped on the Global‑e side)

Response

Name	Type	Description	Mandatory
`responseInfo`	Object `ResponseInfo`	Response information for the API call.	No

ResponseInfo

Parameter Name	Type	Description	Mandatory
`Success`	Boolean	Indicates if the call was successful. Success property value may be only TRUE. Otherwise, ErrorInfo will be returned instead. TRUE - Call was successful FALSE - Call failed For more information see `ErrorInfo`.
`Reason`	String	Text that optionally describes the reason for Success status.

Parameter Name

Type

Description

Mandatory

Success

Boolean

Indicates if the call was successful. Success property value may be only TRUE. Otherwise, ErrorInfo will be returned instead.

TRUE - Call was successful

FALSE - Call failed

For more information see ErrorInfo.

Reason

String

Text that optionally describes the reason for Success status.

Parameter Name	Type	Description
`Code`	String	The error code
`error`	String	The error message
`Description`	String	The error description

Errors

Error Codes

The ErrorInfo includes a field code containing a numeric value.

Code	Description
1001	Order already fully refunded or cancelled
1002	Requested refund amount is greater than the remaining amount available for a refund for this order
1003	Invalid quantity
1004	Refund request must contain at least one refund component
1005	Cartitemid {currentRefundProduct.CartItemId} doesn’t exists for order {orderRefundObj.OrderId
1006	CartItemId {currOrderProduct.CartItemId} exceeded the quantity of the available products to refund

Examples

Request

[
   {
        "CartItemId": "134643",
        "RefundQuantity": "1",
        "RefundAmount": "42",
        "RefundReason": {
            "OrderRefundReasonCode": "RETURN",
            "Name": "RETURN"
        },
        "RefundComments": ""
    }, {
        "CartItemId": "134644",
        "RefundQuantity": "1",
        "RefundAmount": "58",
        "RefundReason": {
            "OrderRefundReasonCode": "RETURN",
            "Name": "RETURN"
        },
        "RefundComments": ""
    }
]

Response Error

{
    "Code": "1006",
    "Error": "Cartitemid 1 exceeded the available products quantity to refund",
    "Description": "After Method ValidateProducts. refund amount: 67.8700 , available loyalty points: 0.0000"
}

CreateOrderRefund API - Out of Stock

The Out of Stock (OOS) feature allows merchants to indicate products as out-of-stock through the CreateOrderRefund API without specifying the refund amount.

This feature enabled the following actions:

Modification of the product quantity.
Recalculation of duties and taxes.
Adjustment of shipping costs (if there are no flat rates).
The update of associated documents.
The Issuing of a product refund.
If all the products within an order are indicated as out of stock, the order status is changed to 'Cancelled by Merchant'.

Refunds

The out-of-stock quantities are indicated by using the product quantity field.
Any provided amount associated with a product with an out-of-stock refund reason is ignored.
If out-of-stock is provided for a product that a product appeasement is made for, only the remaining amounts are refunded.

Mapping

Out-of-stock products must be assigned a pre-mapped refund reason in order to be recognized by the system.

Mapping is established between the merchant's refund reasons and Global-e's internal reasons, as specified in the MapMerchantOrderRefundReasons table,

Examples of codes in the MapMerchantOrderRefundReasons table

Code	Refund Reason
5	Out of Stock
14	Out-of-Stock Item
23	Product out of stock

Errors

Validation Errors

The following situations cause the amend and refund operation to fail and return an error in the CreateOrderRefund response.

Situation	Error Message
Combining various refund reasons, including out-of-stock and non-out-of-stock reasons, within a single `CreateOrderRefund` request.	"Issuing a refund for out-of-stock products alongside other refund reasons is not permitted. Please include any out-of-stock products in a separate call without other refund reasons."
If the quantity of out-of-stock products exceeds the quantity of remaining products.	"The number of out-of-stock products exceeds the number of remaining products."
If the quantity of out-of-stock products is zero or not provided.	"Out-of-stock quantity missing or zero. Please provide a valid quantity."
If a product is declared as out-of-stock for an order in a not allowed status. Note: Out-of-stock products can only be declared for pre-shipped products.	“The current order status %Order status name% does not permit the declaration of out-of-stock products”.

Example

[
   {
      "CartItemId":"39493377065032-0",
      "RefundQuantity":1,
      "RefundAmount":79.00,
      "RefundReason":{
         "OrderRefundReasonCode":"Out of stock",
         "Name":"Out of stock"
      }
   },
   {
      "CartItemId":"39638402039880-1",
      "RefundQuantity":1,
      "RefundAmount":0.00,
      "RefundReason":{
         "OrderRefundReasonCode":"Out of stock",
         "Name":"Out of stock"
      }
   }
]

GetRefundDetails (Merchant to Global-e)

This API provides information about refunds associated with an order. The information includes all the refund details and the refundable amount for each product in the order.

The API returns:

MerchantOrderRefund
Credit note URL

Method/URL

GET https://{globale_api_domain}/v1/orders/{orderId}/refunds

Parameters

Response

Name	Type	Description
`MerchantOrderRefund`	Object Merchant.OrderRefund	Object containing details about the refundable amount for the order.

Merchant.OrderRefund

Parameter Name	Type	Description	Mandatory
`Components`	List of `Merchant.RefundComponent`	The list of `RefundComponent` objects for this order refund.	No
`MerchantGUID`	String	Unique identifier of the Merchant on Global-e.	No
`MerchantOrderId`	String	Order unique identifier on the Merchant’s site returned from a previous call to the `SendOrderToMerchant` method for this order.	No
`MerchantRMANumber`	String	The Merchant’s Returned Merchandize Authorization Number	No
`OrderId`	String	Global‑e order unique identifier.	Yes
`OriginalTotalRefundAmount`	Decimal	The refund amount in the original Merchant currency including the local Merchant’s VAT (currency is specified in `CurrencyCode` property of the respective `Merchant.Order`).	Yes
`Products`	List of `Merchant.RefundProduct`	List of `RefundProduct` objects for this order refund.	No
`RefundComments`	String	Comments for the order refund	No
`RefundReason`	Object `Merchant.OrderRefundReason`	Reason for the order refund	No
`RMANumber`	String	The RMA number taken from the related Return.	No
`ServiceGestureAmount`	Decimal	The “Service gesture” amount in the customer’s currency is included in the `TotalRefundAmount`. “Service gesture” denotes any additional refund granted to the user, on top of the refund related to other components.	No
`TotalRefundAmount`	Decimal	The total refund amount in the end customer’s currency used for this order’s payment (currency is specified in InternationalDetails.`CurrencyCode`property for the respective `Merchant.Order`).	Yes
`WebStoreCode`	String	Code used on the Merchant’s side to identify the web store, as specified in the `WebStoreCode` argument for the `SendCart` method for the cart converted to this order on Global‑e.	No

Merchant.OrderRefundReason

Parameter Name	Type	Description	Mandatory
`Name`	String	Order refund reason name.
`OrderRefundReasonCode`	String	Code denoting the order refund reason on the Merchant’s site (to be mapped on the Global‑e side). If not mapped, Global‑e internal code will be specified instead.

Merchant.RefundComponent

Parameter Name	Type	Description
`Amount`	Decimal	The refund amount in customer currency.
`ComponentType`	String	Products, Shipping, Duties, `PrepaidReturn` or `ServiceGesture`.
`IsChargedToMerchant`	Boolean	Indicates if the component is charged to the Merchant or to Global-e. TRUE - Component is charged to the Merchant (default) FALSE - Component is charged to Global‑e 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: A component `PrepaidReturn` – it should always be `IsChargedToMerchant` = TRUE.
`OriginalAmount`	Decimal	The refund amount in Merchant currency.

Merchant.RefundProduct

Parameter Name	Type	Description	Mandatory
`CartItemID`	String	Identifier of the line item on the Merchant’s site. This property is mandatory and should be equal to the respective Product’s `CartItemId` originally specified in the `SendCart` API for the order being refunded	Yes
`OriginalRefundAmount`	Decimal	The refund amount in the original Merchant currency including the local Merchant’s VAT for this product line item, before applying any price modifications (i.e. part of or the full value paid by Global-e to the Merchant, as was specified in `Merchant.Product.Price` for the respective order.
`ProductCode`	String	Product SKU or Product Variant ID according to merchant configuration. Can be used as a Product Identifier instead of `CartItemId`. If there are multiple products with the same identifier, we choose one of them arbitrarily.	No
`RefundAmount`	Decimal	The refund amount for this product line item in customer currency used for the payment of this order
`RefundComments`	String	Comments for this product’s refund	No
`RefundQuantity`	Decimal	Product quantity (i.e. a part of the originally ordered quantity) that the refund refers to
`RefundReason`	Object `Merchant.OrderRefundReason`	Reason for this product’s refund	No
`Sku`	String	This field is obsolete. Use `ProductCode` instead.	No

Merchant.OrderRefundReason

Parameter Name	Type	Description	Mandatory
`Name`	String	Order refund reason name.
`OrderRefundReasonCode`	String	Code denoting the order refund reason on the Merchant’s site (to be mapped on the Global‑e side). If not mapped, Global‑e internal code will be specified instead.

Errors

Code	Description
400	Bad Request. Information cannot be parsed or violates Global-e policies. For example: Order ID not found.
500	Request was successfully parsed with no violations detected, but there was a failure during request handling.

Code

Description

400

Bad Request.

Information cannot be parsed or violates Global-e policies. For example: Order ID not found.

500

Request was successfully parsed with no violations detected, but there was a failure during request handling.

Examples

Response

{
  "OrderId": "string",
  "MerchantOrderId": "string",
  "MerchantInternalOrderId": "string",
  "WebStoreCode": "string",
  "WebStoreInstanceCode": "string",
  "Refunds": [
    {
      "RefundID": "string",
      "RMANumber": "string",
      "MerchantRMANumber": "string",
      "FullRefund": true,
      "ProductsDutiesRefund": true,
      "ShippingRefund": true,
      "RefundAsGiftCard": null,
      "TotalRefundAmount": "string",
      "OriginalTotalRefundAmount": "string",
      "ServiceGestureAmount": "string",
      "TotalMoneyRefundAmount": "string",
      "DutiesAmount": "string",
      "ShippingAmount": "string",
      "CustomerPrepaidRefundAmount": "string",
      "OriginalCustomerPrepaidRefundAmount": "string",
      "TotalGiftCardsRefundAmount": "string",
      "TotalGiftCardsRefundAmountinMerchantCurrency": 0,
      "TotalLoyaltyPointsRefunded": 0,
      "TotalLoyaltyPointsRefundAmount": 0,
      "GiftCardsData": [
        {
          "CardId": 0,
          "OtherFields": "..."
        }
      ],
      "ExternalReference": "string",
      "InitiatedBy": "string",
      "CurrencyCode": "string",
      "OriginalCurrencyCode": "string",
      "RefundReason": {
        "OrderRefundReasonCode": "string",
        "Name": "string"
      },
      "RefundProducts": [
        {
          "CartItemId": "string",
          "RefundQuantity": "string",
          "RefundAmount": "string",
          "OriginalRefundAmount": "string",
          "RefundAmountPercent": "string",
          "RefundReason": "string",
          "RefundComments": "string",
          "Sku": "string",
          "ProductCode": "string",      
          "productGroupCode": "string",            
          "ProductCodeSecondary": "string",
          "productGroupCodeSecondary": "string"      
        }
      ],
      "RefundComponents": [
        {
          "Amount": "string",
          "OriginalAmount": "string",
          "IsChargedToMerchant": "string",
          "ComponentType": "string"
        }
      ],
      "RefundComments": "string",
      "RefundDocument": [
        {
          "DocumentData": "string",
          "CreditNoteUrl": "string",
          "DocumentTypeCode": "string",
          "DocumentTypeName": "string",
          "DocumentExtension": "string"
        }
      ]
    }
  ],
  "RefundableAmount": {
    "CurrencyCode": "string",
    "TotalCreditAmount": 0,
    "RefundableShippingAmount": 0,
    "RefundableDutiesAmount": 0,
    "ProductRefundableAmount": [
      {
        "CartItemId": "string",      
        "Sku": "string", 
        "ProductCode": "string",      
        "productGroupCode": "string",            
        "ProductCodeSecondary": "string",
        "productGroupCodeSecondary": "string",        
        "RefundableTotalAmount": 0,
        "RefundableQuantity":1
      }
    ]
  }
}

Error

{
   "error": {
        "code": "String",
	"message": "String",
	"description": "String"	
   }
}

Documentation Portal

Refund Methods

CreateOrderRefund (Merchant to Global-e)

Parameters

OrderRefundDetails

OrderRefundReason

RefundProducts

OrderRefundReason

ResponseInfo

ErrorInfo

Errors

Examples

CreateOrderRefund API - Out of Stock

Errors

Example

GetRefundDetails (Merchant to Global-e)

Parameters

Merchant.OrderRefund

Merchant.OrderRefundReason

Merchant.RefundComponent

Merchant.RefundProduct

Merchant.OrderRefundReason

Errors

Examples

Search results