Skip to main content

Documentation Portal

Refunds via API

The CreateOrderRefund 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 attributes are required in the system (OMS/ERP/MW) executing the Refunds calls:

  • Global‑e order number (and not ecommerce platform or another system)

  • Product “cartItemId” or “SKU” as specified in the cart shared between Global‑e and the ecommerce platform

Full Refunds and Total Amount Logic

The CreateOrderRefund API issues a refund for the order specified in orderRefund argument.

Optionally may include the list of RefundProductsor 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 CreateOrderRefundAPI.

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

Examples

Success Response

The success response contains the OrderRefundInfo object.

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

Error Response

The error response contains ErrorInfo:

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

Object Processing Error Response

Error response as the OrderRefundInfo object is not processed. (Reason is optional.)

{
     "Success": false,
     "Reason": "Processing error detail",
     "NotifyOrderRefund": null
}
Use Cases - Examples

Examples of headers and body - Note: No refund comments or reasons are used in samples.

{{geApiUrl}}/Order/CreateOrderRefund?merchantGUID={{guid}}&orderRefund=<orderRefundSample>
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.

Headers

Body

OrderRefund= 

 {
     "OrderId": "GE95135467GB",
    "FullRefund": true
}
Full Product Refund

For full product refunds, no refund value is required. Global‑e will establish it from order.

Single product

Headers

Body

OrderRefund=

{

"OrderId": "GE95135467GB"

}

[

{ "CartItemId": "1381109", "RefundQuantity": 1 }

]

Multiple Products

Headers

Body

OrderRefund= 

{
    "OrderId": "GE95135467GB"
}

[
    {
        "CartItemId": "1381109",
        "RefundQuantity": 2
    },
    {
        "CartItemId": "2371567",
        "RefundQuantity": 1
    }
]
Products with associated duties paid by the customer

Headers

Body

OrderRefund=

{

"OrderId": "GE95135467GB",
"ProductsDutiesRefund": true

}

[

{ "CartItemId": "1381109", "RefundQuantity": 1 },

{ "CartItemId": "2371567", "RefundQuantity": 1 }

]

Product with shipping

Headers

Body

OrderRefund=

{

"OrderId": "GE95135467GB",
"ShippingRefund": true

}

[

{ "CartItemId": "1381109", "RefundQuantity": 1 }

]

Shipping Only

Headers

Body

OrderRefund= 

{
     "OrderId": "GE95135467GB",
     "ShippingRefund": true
}

[]
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.

Headers

Body

OrderRefund= 

{
     "OrderId": "GE95135467GB",
    "TotalRefundAmount": "320"
}

[
     {
        "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.

Headers

Body

OrderRefund= 

{
     "OrderId": "GE95135467GB"
}

[
    {
        "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.

Headers

Body

OrderRefund= 

{
    "OrderId": "GE95135467GB",
    "ShippingAmount": "10",
    "TotalRefundAmount": "10"
}

[]
Service gesture

Example: Customer order placed in Australian dollars. Refunding 50 AUD as a service gesture because of a delay in dispatch.

Headers

Body

OrderRefund= 

{
  "OrderId": "GE95135467GB",
  "ServiceGestureAmount": "50",
  "TotalRefundAmount": "50"
}

[]
Duties Refund

Headers

Body

OrderRefund= 

 {
    "OrderId": "GE95135467GB",
    "DutiesAmount": "60",
    "TotalRefundAmount": "60"
}

[]
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.

Headers

Body

OrderRefund= 

{
   "OrderId": "GE95135467GB",
   " ShippingAmount": "40",
}

[
     {
        "CartItemId": "1381109",
        "RefundQuantity": 2
    }
    ]
Deduction of Return Shipping

Example: A German shopper is returning an item to a merchant in the United States.

The return shipping cost is €5.00 so the merchant deducts €5.00 from the refund.

Headers

Body

OrderRefund= 

{
     "OrderId": "#4999",
     "CustomerPrepaidRefundAmount":5
}

[ 
    {
        "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

ErrorInfo

#

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

ResponseInfo

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