Skip to main content

Documentation Portal

Refunds Notifications (from Global‑e)

NotifyOrderRefund

Introduction

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

API URL

[POST] https://www.merchant-site-domain.com/order/refund

API Request Structure
Merchant.OrderRefund

Name

Required

Type

Description

MerchantGUID

Yes

String

Unique identifier of the Merchant on Global-e.

OrderId

Yes

String

Global‑e order unique identifier.

MerchantOrderId

No

String

Order unique identifier on the Merchant’s site returned from a previous call to the SendOrderToMerchant method for this order.

OriginalTotalRefundAmount

Yes

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).

TotalRefundAmount

Yes

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).

RefundReason

No

OrderRefundReason

Reason details for the order refund

RefundComments

No

String

Comments for the order refund

Products

No

RefundProduct[]

List of RefundProduct objects for this order refund.

ServiceGestureAmount

No

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.

WebStoreCode

No

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.

Components

No

RefundComponent[]

List of RefundComponent objects for this order refund.

MerchantOrderRefund: 

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

Name

Required

Type

Description

OrderRefundReasonCode

No

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

Name

No

String

Order refund reason name

RefundProduct

Name

Required

Type

Description

CartItemId

Yes

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

RefundQuantity

Yes

String

Product quantity (i.e. a part of the originally ordered quantity) that the refund refers to.

OriginalRefundAmount

No

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).

RefundAmount

Yes

String

Refund amount for this product line item in the end customer’s currency used for this order’s payment.

RefundReason

No

RefundReason

Reason for this product’s refund

RefundComments

No

String

Comments for this product’s refund

RefundComponent

Name

required

Type

Description

Amount

Yes

String

The refund amount is in customer currency.

OriginalAmount

Yes

String

The refund amount is in merchant currency.

IsChargedToMerchant

Yes

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.

ComponentType

Yes

String

Products, Shipping, Duties, PrepaidReturn, or ServiceGesture.

TotalGiftCardsRefundAmount

No

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.

TotalGiftCardsRefundAmountinMerchantCurrency

No

Decimal

The total refund amount in merchant currency is used for this order’s payment.

RefundAsGiftCard

No

Bool

Declares, to refund the order as a gift card.

API Response Structure
ResponseInfo

Name

required

Type

Description

InternalOrderId

No*

(Optional in case of error, failure, or if the action is not related to a specific order)

String

Order unique identifier on the Merchant’s site

OrderId

No

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).

StatusCode

No*

(Optional in case of error or failure)

String

Code denoting the order status on the Merchant’s site (to be mapped on the Global‑e side).

PaymentCurrencyCode

No

String

3-char ISO currency code for the order (if payment was processed in the respective API method call).

PaymentAmount

No

String

The total payment amount in PaymentCurrency is charged for the order (if payment was processed in the respective API method call).

Success

Yes

Bool

Indicates if the call has succeeded. FALSE denotes an error or failure.

ErrorCode

No

String

Error code to be returned when an error occurs.

Message

No

String

Optional response message. In case of an error, this property indicates the error message text.

Description

No

String

Optional response description. In case of an error, this property indicates the error message description.

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"
    
}