RefundGiftCard

Call RefundGiftCard to return the used gift card balance when the order is cancelled or a new Refund has been created.

Global‑e sends the list of all applied gift cards and the total amount to refund for gift cards in both currencies (customer currency and gift card currency), as well as the conversion rate. The Merchant’s platform determines the actual refund values to be refunded for each gift card and returns the respective values in the API response accordingly.

For each gift card, set the following in response:

GiftCardData.RefundedBalanceInGiftCardCurrency – must not exceed the provided value of GiftCardData.BalanceUsedInCardCurrency
GiftCardData.RefundedBalanceInCustomerCurrency – must not exceed the provided value of GiftCardData.BalanceUsedInCustomerCurrency
GiftCardData.IsRefundSuccess
- Set to true: If the two previous values for the card and values are successfully refunded.
- Set to false: If the refund was added but something went wrong.

If no refunds are added for the particular card, do not set these values.

Method/URL

https://www.merchant-site-domain.com/refund-gift-card-url

Parameters

Request

Requests can contain more parameters than listed.

Name	Type	Description	Mandatory
order	Object RefundGiftCardRequest	Contains information about the gift card refund.	Yes

Response

Note

Some response values are encoded and require the merchant to decode them, for example URLs, addresses, emails, and phone numbers.

Name	Type	Description	Mandatory
order	Object RefundGiftCardResponse	Contains information about the response to the API call for gift card refunds.	Yes

Objects for RefundGiftCard API

RefundGiftCardRequest

Parameter Name	Type	Description
`Cards`	List of `GiftCardData`	List with gift cards data objects
`ConversionRate`	Decimal	Rate of conversion from gift card currency to customer currency
`MerchantGUID`	String	Merchant unique identifier
`OrderId`	String	Global‑e Order ID
`TotalToRefundInCustomerCurrency`	Decimal	The total value to refund for all gift cards in customer currency
`TotalToRefundInGiftCardCurrency`	Decimal	The total value to refund for all gift cards in gift card currency

GiftCardData

The GiftCardData model is used for most calls where multiple cards are passed. See Base Gift Card Model.

Parameter Name	Type	Description	Mandatory
`BalanceInCustomerCurrency`	Decimal	Total available amount in customer currency
`BalanceInGiftCardCurrency`	Decimal	Total available amount in gift card currency
`BalanceUsedInCardCurrency`	Decimal	Amount to redeem in gift card currency
`BalanceUsedInCustomerCurrency`	Decimal	Amount to redeem in gift user currency
`CardFields`	Dictionary<String, String>	Key value pairs of each field defined in the configuration
`CardId`	Decimal	id of the card in the DB table on the Global‑e side
`CustomerCurrencyCode`	String	User currency code (checkout currency)
`ErrorCode`	String	Code of the error	No
`ErrorText`	String	Error message	No
`GiftCardCurrencyCode`	String	Gift card currency code
`IsRefundSuccess`	Boolean	The refund status. TRUE - Refund was successfully applied to the gift card FALSE - Refund failed or there is no refund on the card
`RedeemTransactionId`	String	The value that is set as a result of card redemption (should be provided by the platform)
`RefundedBalanceInCustomerCurrency`	Decimal	The amount of refunded money in customer currency
`RefundedBalanceInGiftCardCurrency`	Decimal	The amount of refunded money in gift card currency

BaseGiftCard

The CardData model is used for most calls where multiple cards are passed.

Parameter Name	Type	Description
`BalanceUsedInCardCurrency`	Decimal	Amount to redeem in gift card currency
`CardFields`	Dictionary<String,String>	The Value of each field is defined in the configuration. Key – defined field name Value – user input data
`CardHash`	String	Unique hash generated for each card
`CardId`	Long	ID of card in DB table on Global-e CORE side
`CustomerCurrencyCode`	String	User currency code (checkout currency)
`ErrorCode`	String	Code of error which should be set during Redeem and Refund calls
`ErrorText`	String	Text of error message
`GiftCardCurrencyCode`	String	Gift card currency code
`IsRefundSuccess`	Boolean	True if the refund is successful False if the refund fails If there is no refund on the card it should be NULL
`RedeemTransactionId`	String	Value which is set as a result of card redemption
`RefundedBalanceInCustomerCurrency`	Decimal	Amount of refunded money in customer currency (should be set in refund API call)
`RefundedBalanceInGiftCardCurrency`	Decimal	Amount of refunded money in gift card currency (should be set in refund API call)

RefundGiftCardResponse

Parameter Name	Type	Description
`Cards`	List of `GiftCardData`	List with gift cards data objects data
`ErrorCode`	String	Code of the error
`ErrorText`	String	Error message
`IsRefunded`	Boolean	Indicates if the amounts of redeemed cards was successfully returned TRUE - Successfully refunded. FALSE - Refund not successful.

GiftCardData

The GiftCardData model is used for most calls where multiple cards are passed. See Base Gift Card Model.

Parameter Name	Type	Description	Mandatory
`BalanceInCustomerCurrency`	Decimal	Total available amount in customer currency
`BalanceInGiftCardCurrency`	Decimal	Total available amount in gift card currency
`BalanceUsedInCardCurrency`	Decimal	Amount to redeem in gift card currency
`BalanceUsedInCustomerCurrency`	Decimal	Amount to redeem in gift user currency
`CardFields`	Dictionary<String, String>	Key value pairs of each field defined in the configuration
`CardId`	Decimal	id of the card in the DB table on the Global‑e side
`CustomerCurrencyCode`	String	User currency code (checkout currency)
`ErrorCode`	String	Code of the error	No
`ErrorText`	String	Error message	No
`GiftCardCurrencyCode`	String	Gift card currency code
`IsRefundSuccess`	Boolean	The refund status. TRUE - Refund was successfully applied to the gift card FALSE - Refund failed or there is no refund on the card
`RedeemTransactionId`	String	The value that is set as a result of card redemption (should be provided by the platform)
`RefundedBalanceInCustomerCurrency`	Decimal	The amount of refunded money in customer currency
`RefundedBalanceInGiftCardCurrency`	Decimal	The amount of refunded money in gift card currency

BaseGiftCard

The CardData model is used for most calls where multiple cards are passed.

Parameter Name	Type	Description
`BalanceUsedInCardCurrency`	Decimal	Amount to redeem in gift card currency
`CardFields`	Dictionary<String,String>	The Value of each field is defined in the configuration. Key – defined field name Value – user input data
`CardHash`	String	Unique hash generated for each card
`CardId`	Long	ID of card in DB table on Global-e CORE side
`CustomerCurrencyCode`	String	User currency code (checkout currency)
`ErrorCode`	String	Code of error which should be set during Redeem and Refund calls
`ErrorText`	String	Text of error message
`GiftCardCurrencyCode`	String	Gift card currency code
`IsRefundSuccess`	Boolean	True if the refund is successful False if the refund fails If there is no refund on the card it should be NULL
`RedeemTransactionId`	String	Value which is set as a result of card redemption
`RefundedBalanceInCustomerCurrency`	Decimal	Amount of refunded money in customer currency (should be set in refund API call)
`RefundedBalanceInGiftCardCurrency`	Decimal	Amount of refunded money in gift card currency (should be set in refund API call)

Examples

Request

{
    "MerchantGUID": " abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "Cards": [{
            "CardId": 2290,
            "BalanceInGiftCardCurrency": 1000.000000,
            "BalanceInCustomerCurrency": 906.270000,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "EUR",
            "BalanceUsedInCardCurrency": 273.990000,
            "BalanceUsedInCustomerCurrency": 248.3100,
            "RedeemTransactionId": "TestSuccessRedeemTransaction",
            "CardFields": {
                "CardId": "card1000"
            }
        }
    ],
    "TotalToRefundInCustomerCurrency": 115.0,
    "TotalToRefundInGiftCardCurrency": 126.89,
    "ConversionRate": 0.906269,
    "OrderId": "GE927127"
}

Response

{
    "Cards": [{
            "CardId": 2290,
            "BalanceInGiftCardCurrency": 1000.000000,
            "BalanceInCustomerCurrency": 906.270000,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "EUR",
            "BalanceUsedInCardCurrency": 273.990000,
            "BalanceUsedInCustomerCurrency": 248.3100,
            "RedeemTransactionId": "TestSuccessRedeemTransaction",
            "CardFields": {
                "CardId": "card1000"
            },
            "RefundedBalanceInGiftCardCurrency": 126.89,
            "RefundedBalanceInCustomerCurrency": 115.0,
            "IsRefundSuccess": true
        }
    ],
    "TotalToRefundInCustomerCurrency": 115.0,
    "TotalToRefundInGiftCardCurrency": 126.89,
    "ConversionRate": 0.906269,
    "OrderId": "GE2991190US"
}

Documentation Portal

RefundGiftCard

Parameters

Note

Objects for RefundGiftCard API

RefundGiftCardRequest

GiftCardData

BaseGiftCard

RefundGiftCardResponse

GiftCardData

BaseGiftCard

Examples

Search results