ValidateVoucher (Global-e to Merchant)

Note

This API is part of Global-e's extensions and plug-ins. Merchants do not need to implement this API unless a custom integration is required.

This API returns new CartToken in the CartToken attribute. The API call is used to help validate vouchers/coupons used on the Checkout page. If the voucher is valid, the merchant’s platform is responsible for applying this voucher to the shopper's basket and executing a new SendCart / SendCartV2 API call to Global‑e, with an indication of the newly generated discount for this voucher or coupon. The new CartToken returned from this call is returned in the CartToken attribute.

Method/URL

https://www.merchant-site-domain.com/checkout-validate-cart-voucher-url

Parameters

Request

Name	Type	Description	Mandatory
Merchant.CartVoucherValidation	Object Merchant.CartVoucherValidation	Provides information related to validating a voucher in a cart.

Merchant.CartVoucherValidation

Parameter Name	Type	Description	Mandatory
`CartHash`	String	Cart hash originally specified in `merchantCartHash` argument for `SendCart` method for the cart converted to this order on Global‑e.
`CartId`	String	Identifier of the cart on the Merchant’s site originally specified in `merchantCartToken` argument for `SendCart` method for the cart converted to this order on Global‑e.
`CartToken`	String	The value returned from the previous call to `SendCart` for the same client (must be stored in the client session or persistent cookie on the Merchant’s side). This parameter is used to support cart updates.
`CountryCode`	String	2-char ISO country code
`CurrencyCode`	String	3-char ISO currency code.
`Discounts`	List of `Merchant.DiscountVoucherValidation`	Cart discounts for voucher validation.
`FreeShippingCouponCode`	String	The Merchant free shipping coupon code applied by the end customer.
`IsFreeShipping`	Bool	Indicates if the Merchant offers free international shipping to the end customer.
`MerchantGUID`	String	Unique identifier of the Merchant on Global-e.
`Products`	List of `Merchant.ProductVoucherValidation`	Cart products for voucher validation.
`UserId`	String	Internal User identifier on the Merchant’s site in case it was specified in the `SendCart` call.	No
`VoucherCode`	String	The voucher code specified on the Merchant site.
`VoucherType`	Decimal	Enumeration of `VoucherTypes`: 1 - `DiscountVoucher`
`WebStoreCode`	String	Code used on the Merchant’s side to identify the web store where the current cart is originating from. This code should be used in case of a multi-store setup on the Merchant’s site.
`WebStoreInstanceCode`	String	Code used on the Merchant’s side to identify the web store instance where the current cart is originating from. This code should be used in case of multi-store domains set up on the Merchant’s site.

Merchant.DiscountVoucherValidation

Parameter Name	Type	Description	Mandatory
`CouponCode`	String	Merchant `CouponCode` used for this discount (applicable to coupon-based discounts only)	No
`Description`	String	Discount textual description	No
`DiscountCode`	String	Discount code originally specified in the `Discount.DiscountCode` property of the respective discount in `SendCart` method for the cart converted to this order on Global‑e.	No
`DiscountSource`	Enum	The enum `DiscountSource` has the following possible values: 1 = Merchant 2 = FixedShippingPrice 3 = PercentageCartPrice 4 = HiddenForceDDP 5 = Amend 6 = RemoteAreaSurchargeSubsidy 7 = LoyaltyPoints 8 = PaymentCharge 9 = ReplacementOrder	Yes
`DiscountType`	Decimal	Discount type (“Cart”, “Shipping”, etc.), as defined in the `DiscountTypeOptions` enumeration described in the Discount class in this document.
`InternationalPrice`	Decimal	Discount value in end customer’s currency (specified in `InternationalDetails.CurrencyCode` property for the respective `Merchant.Order`), after applying country coefficient, FX conversion, and `IncludeVAT` handling.	No
`LocalVATRate`	Decimal	The VAT rate that would be applied to this discount if the order was placed by the local customer. This value must be specified if `UseCountryVAT` for the current Country is TRUE and therefore the `VATRate` property denotes the VAT for the target country.	No
`LoyaltyVoucherCode`	String	Loyalty Voucher code originally specified in `Discount.LoyaltyVoucherCode` property of the respective discount in `SendCart` method for the cart converted to this order on Global‑e.	No
c	String	Discount name
`Price`	Decimal	Discount value in the currency defined in the `CurrencyCode` property of the respective `Merchant.Order` object for the order being submitted to the Merchant.
`ProductCartItemId`	String	Identifier of the product cart item related to this discount on the Merchant’s site originally specified in the `Discount.ProductCartItemId` property of the respective discount in the `SendCart` method for the cart converted to this order on Global‑e.	No
`VATRate`	Decimal	The VAT rate applied to this discount

Merchant.ProductVoucherValidation

Parameter Name	Type	Description
`CartItemId`	String	Identifier of the cart item on the Merchant’s site originally specified in the `Product.CartItemId` property of the respective product in the `SendCart`method for the cart converted to this order on Global‑e.
`CartItemOptionId`	String	Identifier of the child cart item “option” on the Merchant’s site originally specified in the Product.CartItemOptionId property of the respective product in the `SendCart` method for the cart converted to this order on Global‑e.
`Categories` - DEPRECATED	List of String	List of categories mapped for current cart product.
`HandlingCode`	String	Code applicable to the product on the Merchant’s site. This code may be optionally used by the Merchant to trigger a certain business logic when this product is included in the order posted back to the Merchant’s site with the `SendOrderToMerchant` method.
`ParentCartItemId`	String	Identifier of the current item’s parent cart item on the Merchant’s site originally specified in the `Product.ParentCartItemId`property of the respective product in the `SendCart` method for the cart converted to this order on Global‑e.
`Price`	Decimal	Product price.
`Quantity`	Decimal	Product ordered quantity.
`Sku`	String	SKU code used to identify the product on the Merchant’s site (to be mapped on the Global‑e side).
`VATRate`	Decimal	The VAT rate applied to this product.

Response

Name	Type	Description	Mandatory
Merchant.VoucherValidationResponse	Object Merchant.VoucherValidationResponse	Provides information related to the voucher validation.

Merchant.VoucherValidationResponse

Parameter Name	Type	Description
`CartToken`	String	`CartToken` returned from the new `SendCart` / `SendCartV2` API call, executed after the voucher has been applied to the respective user’s basket
`IsVoucherValid`	Boolean	Indicates if the voucher is valid. TRUE - Voucher is valid. FALSE - Voucher is not valid.
`ValidationFaliureMessage`	String	Error message in case voucher is not valid
`VoucherRestrictions`	List of `Merchant.VoucherValidationRestriction`	List of validation restrictions applied to vouchers
`VoucherType`	Decimal	Enumeration of `VoucherTypes`: 1 - DiscountVoucher

Merchant.VoucherValidationRestriction

Parameter Name	Type	Description	Mandatory
`RestrictionEntityCode`	String	Country code value.
`VoucherValidationRestrictionType`	Decimal	Enumeration of the voucher value restriction type: 0 - Country

Parameter Name

Type

Description

Mandatory

RestrictionEntityCode

String

Country code value.

VoucherValidationRestrictionType

Decimal

Enumeration of the voucher value restriction type:

0 - Country

Documentation Portal