Skip to main content

Documentation Portal

Refunds Notifications (from Global‑e)

Introduction

The NotifyOrderRefund API notifies the merchant about Global-e initiated refund issued to the end customer.

API Request Structure

Name	Type	Description	Mandatory
MerchantGUID	String	Unique identifier of the Merchant on Global-e.	Yes

MerchantOrderRefund:

{refund header fields, OrderRefundReason{}, Products[], Components[]}

API Response Structure

Name	Type	Description	Mandatory
Description	String	Optional response description. In case of an error, this property indicates the error message description.	No
ErrorCode	String	Error code to be returned when an error occurs.	No
InternalOrderId	String	Order unique identifier on the Merchant’s site	No* (Optional in case of error, failure, or if the action is not related to a specific order)
Message	String	Optional response message. In case of an error, this property indicates the error message text.	No
OrderId	String	Order identifier on the Merchant’s site used for display and reporting purposes only. Unlike InternalOrderId, this identifier is not necessarily unique over time, as the Merchant’s site may potentially reuse it (for example after deleting the old order having the same OrderId).	No
PaymentAmount	String	The total payment amount in PaymentCurrency is charged for the order (if payment was processed in the respective API method call).	No
PaymentCurrencyCode	String	3-char ISO currency code for the order (if payment was processed in the respective API method call).	No
Success	Bool	Indicates if the call has succeeded. FALSE denotes an error or failure.	Yes
StatusCode	String	Code denoting the order status on the Merchant’s site (to be mapped on the Global‑e side).	No* (Optional in case of error or failure)

API Request Sample

{
    "MerchantOrderId": "00708107",
    "MerchantInternalOrderId": "00708107",
    "RefundId": "443847",
    "RMANumber": null,
    "MerchantRMANumber": null,
    "MerchantGUID": "0511dy1d-cuc6-4es6-a5f1-64dc648348a7",
    "Products": [
        {
            "CartItemId": "1",
            "RefundQuantity": "1",
            "OriginalRefundAmount": "31.92",
            "RefundAmount": "135.90",
            "RefundAmountPercent": null,
            "RefundReason": {
                "OrderRefundReasonCode": "Did Not Fit",
                "Name": "Did Not Fit"
            },
            "RefundComments": null,
            "Sku": "412315929486"
        },
        {
            "CartItemId": "2",
            "RefundQuantity": "1",
            "OriginalRefundAmount": "31.92",
            "RefundAmount": "135.90",
            "RefundAmountPercent": null,
            "RefundReason": {
                "OrderRefundReasonCode": "Did Not Fit",
                "Name": "Did Not Fit"
            },
            "RefundComments": null,
            "Sku": "412319741121"
        }
    ],
    "Components": [
        {   
            "Amount": "271.80",
            "OriginalAmount": "63.84",
            "IsChargedToMerchant": "TRUE",
            "ComponentType": "Products"
        }
    ],
    "TotalLoyaltyPointsRefunded": 0,
    "TotalLoyaltyPointsRefundAmount": 0.0,
    "OrderId": "GE10068801664SG",
    "TotalRefundAmount": "271.80",
    "RefundReason": {
        "OrderRefundReasonCode": "Did Not Fit",
        "Name": "Did Not Fit"
    },
    "RefundComments": "Auto Refund due to Return",
    "OriginalTotalRefundAmount": "63.84",
    "ServiceGestureAmount": "",
    "WebStoreCode": null,
    "WebStoreInstanceCode": null,
    "FullRefund": false,
    "TotalMoneyRefundAmount": null,
    "TotalGiftCardsRefundAmount": "0",
    "GiftCardsData": null,
    "TotalGiftCardsRefundAmountinMerchantCurrency": 0.0,
    "RefundAsGiftCard": false
}

API Response Sample

Success Example

 {
    "Success ": "True ",
    "Message": "error message",
    "Description": "error  description"
}

Failure Example

{
     "Success ": "False ",
     "Message": "error message",
     "Description": "error  description"
    
}

Classes

API Request Structure

Name	Type	Description	Mandatory
Components	`RefundComponent[]`	List of `RefundComponent` objects for this order refund.	No
MerchantGUID	String	Unique identifier of the Merchant on Global-e.	Yes
MerchantOrderId	String	Order unique identifier on the Merchant’s site returned from a previous call to the `SendOrderToMerchant` method for this order.	No
OrderId	String	Global‑e order unique identifier.	Yes
OriginalTotalRefundAmount	String	The refund amount is in the original Merchant’s currency including the local Merchant’s VAT (currency is specified in `CurrencyCode` property of the respective Merchant. Order).	Yes
Products	`RefundProduct[]`	List of RefundProduct objects for this order refund.	No
RefundReason	`OrderRefundReason`	Reason details for the order refund	No
RefundComments	String	Comments for the order refund	No
ServiceGestureAmount	String	“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
TotalRefundAmount	String	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 site to identify the web store, as specified in `WebStoreCode` argument for SendCart method for the cart converted to this order on Global‑e.	No

MerchantOrderRefund:

{refund header fields, OrderRefundReason{}, Products[], Components[]}

OrderRefundReason

Name	Type	Description	Mandatory
Name	String	Order refund reason name	No
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	No

RefundComponent

Name	Type	Description	Mandatory
Amount	String	The refund amount is in customer currency.	Yes
ComponentType	String	Products, Shipping, Duties, PrepaidReturn, or ServiceGesture.	Yes
IsChargedToMerchant	String (“TRUE” / “FALSE”)	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. The exception is a component PrepaidReturn – it should always be IsChargedToMerchant = TRUE.	Yes
OriginalAmount	String	The refund amount is in merchant currency.	Yes
RefundAsGiftCard	Bool	Declares, to refund the order as a gift card.	No
TotalGiftCardsRefundAmountinMerchantCurrency	Decimal	The total refund amount in merchant currency is used for this order’s payment.	No
TotalGiftCardsRefundAmount	String	The parameter will be the TotalRefundAmount converted by the Daily Spot Rate the parameter will be displayed in the API call only when the feature is enabled and will have value, only when the refund includes returns.	No

RefundProduct

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
RefundQuantity	String	Product quantity (i.e. a part of the originally ordered quantity) that the refund refers to.	Yes
OriginalRefundAmount	String	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
RefundAmount	String	Refund amount for this product line item in the end customer’s currency used for this order’s payment.	Yes
RefundReason	RefundReason	Reason for this product’s refund	No
RefundComments	String	Comments for this product’s refund	No

API Response Structure

Name	Type	Description	Mandatory
Description	String	Optional response description. In case of an error, this property indicates the error message description.	No
ErrorCode	String	Error code to be returned when an error occurs.	No
InternalOrderId	String	Order unique identifier on the Merchant’s site	No* (Optional in case of error, failure, or if the action is not related to a specific order)
Message	String	Optional response message. In case of an error, this property indicates the error message text.	No
OrderId	String	Order identifier on the Merchant’s site used for display and reporting purposes only. Unlike InternalOrderId, this identifier is not necessarily unique over time, as the Merchant’s site may potentially reuse it (for example after deleting the old order having the same OrderId).	No
PaymentAmount	String	The total payment amount in PaymentCurrency is charged for the order (if payment was processed in the respective API method call).	No
PaymentCurrencyCode	String	3-char ISO currency code for the order (if payment was processed in the respective API method call).	No
Success	Bool	Indicates if the call has succeeded. FALSE denotes an error or failure.	Yes
StatusCode	String	Code denoting the order status on the Merchant’s site (to be mapped on the Global‑e side).	No* (Optional in case of error or failure)

Would you like to provide feedback? Just click here to suggest edits.