- Documentation Portal
- SDK and API
- General API Reference
- Checkout Methods
Checkout Methods
Note
These methods are implemented by the Global-e extensions and plug-ins and do not need to be implemented by the brand.
SendCartV2
The method sends the end customer’s cart contents from the Merchant’s site to Global-e and returns a unique Cart Token to be further passed by the Merchant’s site to the Global-e checkout widget or to API checkout methods.
Method/URL
POST https://connect.bglobale.com/Checkout/SendCartV2
Parameters
Request
Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| Object | Details about the end customer’s cart contents from the Merchant’s site. Includes user details, product details, discount details, conversion information, vouchers, and any other information required for cart creation | Y |
Object SendCartData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Bool | Indicates if the end customer’s consent to receive emails from Merchants should be pre-selected in Global‑e checkout. TRUE - Preselect consent to receive emails. FALSE - Do not preselect consent. | No |
| Object | Details about the cart currency | |
| String | A string that represents the Merchant order id if it is known already at the point when the user is still in the cart page on the Merchant’s store. | No |
| Object | Data regarding cart price modifications | |
| String | The value returned from the previous call to | |
| String | The end customer’s IP address. | No |
| String | 2-char ISO country code of the shipping country either pre-defined using geo-location or actively selected by the end customer. This may be different from the | |
| Object | Cart culture data | No |
| String | Indicates type of delivery. | |
| List of | List of Discounts to be applied to the cart. Discounts of any type (“cart”, “shipping”, etc.) may be specified. | |
| Object | Holds information required carts that were awarded free international shipping according to the Merchant platform (as opposed to the flat shipping pricing system on the global-e system). | |
| String | The 2-character ISO country code representing the country to which this hub belongs. | |
| Decimal | Identifier of the Global‑e’s Local Hub previously returned by the | |
| Bool | Indicates whether the person placing the order is a customer support agent or a regular customer. TRUE – The customer is a customer support agent and an “Offline order” takes place, FALSE - (default value) – The customer is a regular customer. | No |
| List of | List of JSON-serialized Shipping Options available for local shipping of the order from the Merchant to Global‑e’s Local Hub previously returned by the | |
| Object | Holds information for Merchant-side loyalty points to be applied. | |
| Object | Holds information on the registered user to apply loyalty points on the checkout page. | No |
| String | Hash optionally generated by the Merchant, to be returned to the Merchant with the order API call. This hash may be used for additional cart and order validation purposes on the Merchant’s side. | |
| String | Cart or session identifier used for the cart on the Merchant’s site, to be returned to the Merchant with the order API call. | |
| String | Unique identifier of Merchant internal order ID. | |
| String | Unique identifier of Merchant order ID. | |
| String | The amended Merchant's price for duties. Can be used to declare a value for a free item for customs purposes. Note: Either Used by SendCartV2 API. | |
| String | Name of the Product. Min length: 1 char. No length limit. | |
| String | The original Merchant's price for duties. Can be used to declare a value for a free item for customs purposes. Note: Either Used by SendCartV2 API. | |
| List of Decimal | List of available payment instalment amounts. | |
| Class | Cart price modification data | Optional for Merchants not supporting browsing integration |
| List of | List of Product objects. | |
| String | Currency data used by Global‑e to verify the currency rate. Return the value received in the used currency rate. | |
| String | Indicates the ship-to-shop code. | |
| String | List of JSON-serialized | |
| Object | All available details of the user including all relevant addresses. | |
| Object | Holds information required for VAT exemption within the EU. | |
| Object | Holds information for Merchant-side vouchers to be applied (includes loyalty vouchers and one-time vouchers). | |
| 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. | No |
| 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. | No |
Object CartCurrencyData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | 3-char ISO currency code denoting the end customer’s currency. If not specified, the Merchant’s default currency will be assumed by default | No |
| String | 3-char ISO currency code denoting the original currency on the Merchant’s site (before applying country coefficient and FX conversion). If not specified, the Merchant’s default currency will be assumed by default | No |
Object CartFreeShippingData
Parameter Name | Name | Name | Mandatory |
---|---|---|---|
| String | Merchant’s free shipping | No |
| Boolean | Indicates if the Merchant offers free international shipping to the end customer. TRUE - Free international shipping is offered. FALSE - Free international shipping is not offered. | No |
Object CartLoyaltyData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Loyalty code applicable to the Merchant’s site entered by the end customer in Global‑e checkout | No |
| Decimal | The number of loyalty points to be earned for this purchase by the end customer on the Merchant’s site, as specified in the | No |
| Decimal | The number of loyalty points spent for this purchase. The existing loyalty points handling procedure must be applied to the end customer’s user account. Therefore, the “Loyalty points” type discount must not be applied to the order directly but can be used for display purposes elsewhere in the system (i.e. on the end user’s My Account page). | No |
| Decimal | The total number of loyalty points currently available in the end customer’s user account on the Merchant’s site. | No |
Object CartPriceModificationData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Decimal | The | Mandatory for merchants supporting browsing integration |
| Decimal | The | Mandatory for merchants supporting browsing integration |
| Decimal | The | Mandatory for merchants supporting browsing integration |
Object CartUserDetails
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| List of | All available addresses are taken from the registered customer address book | No |
| String | Internal User identifier on the Merchant’s site | No |
Object AddressDetails
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Address line 1. | No |
| String | Address line 2. | No |
| String | Id of the current address from within the address book | No |
| String | Name of the current address from within the address book | No |
| String | City name. | No |
| String | Company name | No |
| String | 2-char ISO country code | No |
| String | E-mail address | No |
| String | Fax | No |
| String | First name | No |
| String | First name in local culture | No |
| Boolean | Indicates that the current address can be used as a billing address | No |
| Boolean | Indicates that the current address is the default billing address | No |
| Boolean | Indicates that the current address is the default shipping address | No |
| Boolean | Indicates that the current address can be used as a shipping address | No |
| String | Last name | No |
| String | Last name in local culture | No |
| String | Middle name | No |
| String | Phone #1 | No |
| String | Phone #2 | No |
| String | Salutation or title (e.g. Dr., Mr., etc.). | No |
| String | State or province ISO code such as AZ for Arizona (if applicable) | No |
| String | State or province name | No |
| String | User’s personal ID document number | No |
| Object | User’s personal ID document type (e.g. Passport, ID card, etc.) | No |
| String | Zip or postal code | No |
Object UserIdNumberType
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Identification document type name | |
| String | Code denoting a user identification document type (e.g. Passport, ID card, etc.) on the Merchant’s site (to be mapped on the Global‑e side) |
Object CartVATRegistrationData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Boolean | Indicates if the end customer must not be charged VAT. TRUE - Set to TRUE for registered users who have validated their business entity’s VAT Registration Number with the merchant and are therefore VAT exempted. Customer is not charged VAT. FALSE - Customer is charged VAT. | No |
| String | VAT Registration Number of the end customer’s business entity validated with the merchant | No |
Object CartVoucherData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| List of | List of available loyalty vouchers for the registered customer | No |
| Object | One-time voucher information | No |
Object CartOTVoucherData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Amount of the one-time voucher in | No |
| Decimal | One-time voucher code for the cart (for applicable platforms) | No |
| Decimal | One-time voucher currency used for the amount | No |
Object LoyaltyVoucher
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Loyalty Voucher’s textual description | No |
| Decimal | Value of the discount based on the Loyalty Voucher. This value should be specified in the end customer’s currency, after applying country coefficient, FX conversion and | |
| Boolean | Indicates if the Loyalty Voucher is already applied by the end customer to the current cart | |
| Decimal | The VAT rate to be applied to the discount based on this Loyalty Voucher if the order was placed by the local customer. This value must be specified if | No |
| String | Loyalty Voucher’s name | |
| Decimal | The discount value to which the end customer is entitled if this Loyalty Voucher is applied to the cart. This value should be specified in the original Merchant currency including the local VAT, before applying any price modifications. This property always denotes the discount value in the default Merchant’s country, regardless of | |
| Decimal | The VAT rate applied to the discount based on this Loyalty Voucher | |
| String | Code used to identify the Loyalty Voucher on the Merchant’s site |
Object Culture
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | ISO culture code | |
| Boolean | Identifies if language is a “right-to-left” language such as Hebrew and Arabic. TRUE if “right-to-left” language FALSE if not “right-to-left” language | |
| String | Culture name in the respective language, such as “עברית” for he-IL (Hebrew-Israel) culture | |
| String | Culture name |
Object Discount
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Decimal | One of the following possible values of | No |
| String | Merchant Coupon Code used for this discount (applicable to coupon-based discounts only) | No |
| String | Discount textual description | No |
| String | Discount code used to identify the discount on the Merchant’s site. This property may be optionally specified in the | No |
| Decimal | One of the following possible enum values of | |
| Decimal | Discount value as displayed to the customer, after applying country coefficient, FX conversion and | |
| Decimal | VAT rate that would be applied to this discount if the order was placed by the local customer. This value must be specified if | No |
| String | Code used on the Merchant’s site to identify the Loyalty Voucher that this discount is based on | No |
| String | Discount name | |
| Decimal | Discount value in original Merchant currency including the local VAT, before applying any price modifications. This property always denotes the discount value in the default Merchant’s country, regardless of | |
| String | Identifier of the product cart item related to this discount on the Merchant’s site. This property may be optionally specified in the | No |
| Decimal | The VAT rate applied to this discount |
DiscountType Options
One of the following possible values of DiscountTypeOptions
enumeration denoting a type of discount:
DiscountType Option Value | Name | Description |
---|---|---|
1 | Cart discount | Discount related to volume, amount, coupon or another promotion value. |
2 | Shipping discount | Discount aimed to sponsor international shipping. |
3 | Loyalty points discount | Discount applied against the Merchant’s loyalty points to be spent for this purchase. |
4 | Duties discount | Discount aimed to sponsor taxes & duties pre-paid by the end customer in Global‑e checkout. |
5 | Checkout Loyalty Points Discount | Discount applied against the Merchant’s loyalty points in Global‑e checkout. |
6 | Payment Charge | Discount aimed to sponsor “Cash on Delivery” fee. |
CalculationMode Options
One of the following possible values of CalculationModeOptions
enumeration denoting the calculation mode of a discount to be implemented by GEM:
CalculationMode Option Value | Name | Description |
---|---|---|
1 (default) | Percentage discount | The discount value specified in Note: The discount value provided is not a percentage. It represents the discount amount in your domestic currency. The ratio of the discount amount to the domestic price is calculated in the shopper's currency. This same ratio is then applied and deducted in the shopper's currency. |
2 | Fixed in original currency | The discount value specified in |
3 | Fixed in customer currency | The discount value specified in |
Object LoyaltyPoints
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Decimal | The limit loyalty points that the user can use in this order – if not exists the | No |
| Decimal | Value of one loyalty point for earn, in Merchant currency – optional if | No |
| Decimal | Value of one loyalty point for spending, in Merchant currency – optional if | No |
| Decimal | The total loyalty points the user has on account at the Merchant’s site | No |
| Decimal | Value of one loyalty point for earn, in customer currency – optional if | No |
| Decimal | Value of one loyalty point for spending, in customer currency – optional if | No |
Object Product
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| List of | The product’s custom attributes (such as Color, Size, etc.) | No |
| List of | The product’s custom attributes (such as Color, Size, etc.) in English | No |
| String | Estimated date for the backordered item to be in stock | No |
| Object | The product’s brand | No |
| String | Identifier of the cart item on the Merchant’s site. This property may be optionally specified in the | No |
| String | Identifier of the child cart item “option” on the Merchant’s site. This value must be specified if the current cart item is related to a parent item ( | No |
| List of | The product’s categories | No |
| Decimal | The quantity actually set for delivery for the product (to be used in the Order methods described below, as needed) | No |
| String | Description of the Product | |
| String | Description of the Product in English | |
| String | The product’s generic HS Code (not country-specific). If specified this property may assist in mapping the product for duties and taxes calculation purposes. | No |
| String | Optional “gift message” text defined by the end customer to be printed on the product. | No |
| 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 | No |
| Decimal | The product’s height in the Merchant’s default unit of length measure (will be converted to CM). | No |
| String | The Merchant hub code indicates from which hub the product was sent. Note that the HubCode should be mapped to a Global-e hubId on the Global-e side. | No |
| Decimal | The product’s image height in pixels | No |
| String | The product’s image URL | No |
| Decimal | The product’s image width in pixels | |
| Boolean | Boolean specifying if the product was ordered as a backed ordered item. TRUE - The item is back ordered FALSE - The item is not back ordered. Default FALSE. | No |
| Boolean | Indicates if product is available for international shipping. TRUE - The product is not available for international shipping FALSE - The product is available for international shipping | No |
| Boolean | Indicates if the product represents a set of products. TRUE - The product represents a set of other products. If a bundled product has non-zero prices specified (i.e. FALSE - The product does not represent a set of other products. | No |
| Boolean | Indicates if the product’s price is fixed by the Merchant, in the default currency for the country. TRUE - The product’s price is fixed. In this case, all price modifications are disabled for this product. Setting fixed prices is only allowed for the Countries where the FALSE - The product's price is not fixed. | No |
| Boolean | Indicates if the product represents a virtual product that does not have weight or volume and doesn’t affect shipping calculation in Global‑e checkout TRUE - The product represents a virtual product FALSE - The product does not represent a virtual product | No |
| String | The product’s keywords | No |
| Decimal | The product’s length in the Merchant’s default unit of length measure (will be converted to CM). | No |
| Decimal | Line item (product in ordered quantity) sale price in the original Merchant’s currency including the local VAT, before applying any price modifications. This property always denotes the price in the default Merchant’s country, regardless of | No |
| Decimal | Line item (product in ordered quantity) sale price as displayed to the customer, after applying country coefficient, FX conversion and | No |
| Decimal | Product list price (before discounts) as displayed to the customer, after applying country coefficient, FX conversion, rounding rule (if applicable) and | Optional in |
| Object | VAT rate type or class that would be applied to this product if the order was placed by the local customer. This value must be specified if | No |
| Object | Used to hold additional product data such as customer-defined product attributes. | No |
| String | Name of the Product | |
| String | Name of the Product in English | |
| Decimal | The product’s net volume in the Merchant’s default unit of volume measure (will be converted to cubic CM). If specified, this property indicates the net volume of the product, excluding any packaging. | No |
| Decimal | The product’s net weight in the Merchant’s default unit of weight measure (will be converted to grams). If specified, this property indicates the net weight of the product, excluding any packaging. | No |
| Decimal | Ordered quantity for the product (to be used in Checkout / Order methods described below, as needed) | No |
| Decimal | Product list price (before any discounts) in the original Merchant’s currency including the local VAT, before applying any price modifications. This property always denotes the product’s price in the default Merchant’s country, regardless of | Optional in |
| Decimal | Product sale price in the original Merchant’s currency including the local VAT, before applying any price modifications. This property always denotes the product’s price in the default Merchant’s country, regardless of | Optional in SaveProductsList, |
| String | 2-char ISO country code of the product’s country of Origin. The Merchant’s country will be assumed if not specified. | No |
| String | Identifier of the current item’s parent cart item on the Merchant’s site. This value must be specified if the current cart item is related to a parent item ( | No |
| Decimal | Rate applicable to this Product’s | No |
| String | The product class code is used by the Merchant to classify products to use different country coefficient rates. | No |
| String | SKU code used to identify the product on the Merchant’s site (to be mapped on the Global‑e side) | |
| String | Secondary code that may be used to refer to the product on the Merchant’s site. This code may be used in addition to the | No |
| String | Product’s group code on the Merchant’s site (to be mapped on the Global‑e side). Usually, this value is a part of the product SKU code denoting a group of similar products (such as "the same product in different s"). | No |
| String | Secondary code that may refer to the group of products on the Merchant’s site. This code may be used in addition to the | No |
| Decimal | Product sale price as displayed to the customer, after applying country coefficient, FX conversion, rounding rule (if applicable) and | Optional in SaveProductsList, |
| Decimal | Product sale price as displayed to the customer, after applying country coefficient, FX conversion and | No |
| String | Reason for the sale price. This property may optionally contain the text definition of the promo that has resulted in the price deduction for this product (such as “10% discount on all shoes”). | No |
| String | The product’s information page URL | No |
| Object | The product’s VAT category. A product may be assigned to a single VAT category on the Merchant’s site. If available, the respective product’s HS Code should be used as the VAT category for a product. | No |
| Object | Product’s VAT rate type or class | No |
| Decimal | The product’s volume in the Merchant’s default unit of volume measure (will be converted to cubic CM). | Optional, can be used as an alternative for specifying all Height, Width and Length dimensions |
| Decimal | The product’s weight is in the Merchant’s default unit of weight measure (will be converted to grams). The Merchant’s default product weight will be used if not specified. | No |
| Decimal | The product’s width in the Merchant’s default unit of length measure (will be converted to CM). | No |
Object Attributes
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Custom attribute code denoting a Merchant-specific attribute such as size, color, etc. (to be mapped on the Global‑e side) | |
| String | Code used to identify the attribute type on the Merchant’s site such as “size” for size, “color” for "colour", etc. (to be mapped on the Global‑e side) | |
| String | Attribute name |
Object Brand
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Brand code on the Merchant’s site (to be mapped on the Global‑e side) | |
| String | Brand name |
Object Category
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Category code on the Merchant site (to be mapped on the Global‑e side) | |
| String | Category name |
Object MetaData
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| List of | Customer-defined product attributes that allow the personalisation of the product if supported by the merchant’s site (e.g. engraving) |
Object Attributes
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Custom attribute code denoting a Merchant-specific attribute such as size, color, etc. (to be mapped on the Global‑e side) | |
| String | Code used to identify the attribute type on the Merchant’s site such as “size” for size, “color” for "colour", etc. (to be mapped on the Global‑e side) | |
| String | Attribute name |
Object VATCategory
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | VAT Category name | |
| String | Code used to identify the VAT category on the Merchant’s site (to be mapped on the Global‑e side) |
Object VATRateType
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | VAT rate type name | No |
| Decimal | VAT rate decimal value | |
| String | VAT rate type (or class) code on the Merchant’s site (to be mapped on the Global-e side) |
Object ShippingOption
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Carrier’s short name | |
| String | Carrier’s full name | |
| String | Carrier’s title | |
| String | Shipping method code used to identify the shipping option on the Merchant’s site (to be mapped on the Global‑e side) | |
| String | Shipping method name | |
| String | Shipping method title | |
| String | Shipping method description | |
| Decimal | Shipping price in Merchant’s original currency defined in the |
Response Parameters
Name | Type | Description |
---|---|---|
| Object | Contains details about the end customer's cart. |
Object CartInfo
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| String | Cart token for the cart generated on Global‑e side by |
Examples
Request
{ "CountryCode": "AU", "ClientIP": "128.128.128.128", "Currency": { "OriginalCurrencyCode": "GBP", "CurrencyCode": "AUD" }, "PriceModification": { "RoundingRuleId": 103, "PriceCoefficientRate": 1, "IncludeVAT": null }, "Culture": { "PreferedCultureCode": null, "InputDataCultureCode": null, "CultureCode": "en-GB" }, "LocalShippingOptions": [{ "Carrier": "globaleintegration_standard", "CarrierTitle": "globaleintegration_standard", "CarrierName": "globaleintegration_standard", "Code": "globaleintegration_standard", "Method": "globaleintegration_standard", "MethodTitle": "globaleintegration_standard", "MethodDescription": "globaleintegration_standard", "Price": 0, "IsPreferred": true } ], "MerchantCartToken":"3049549", "MerchantOrderId":"45345454", "PlatformURLs":{ "SiteURL": "http://test.com/my_url.html", "RedirectToCartURL": "http://test.com/callback_URL.html" "PaymentCallbackURL": "http://test.com/paymentCallback_URL.html" }, "Products": [{ "ProductCode": "XE08801", "ProductGroupCode": null, "Name": "Socks", "URL": "https://www.test.com/products/08801", "Description": "Naturally Close 5 Pack White Value Trainer Liner Socks", "ImageURL": "https://www.test.com/products/08801.jpg", "SalePrice": "8.95", "OriginalSalePrice": "5", "SalePriceBeforeRounding": "8.905175000000000000", "LocalVATRateType": { "VATRateTypeCode": "merchantVATRateType_20", "Name": "merchantVATRateType_20", "Rate": 20, "InternalVATRateTypeId": 0 }, "OrderedQuantity": 1, "CartItemId": "111", "ImageURL":"https://test.test.com/1.jpg", "IsBackOrdered":false, "IsFixedPrice":true, "ListPrice":58.2, "Attributes": [{ "AttributeCode": "color", "Name": "WHITE", "AttributeTypeCode": "color" }, { "AttributeCode": "size", "Name": "ONE SIZE", "AttributeTypeCode": "size" } ], "MetaData":{ "Attributes": [{ "AttributeKey":"earliestDeliveryDate", "AttributeValue":"1717763520" }, { "AttributeKey":"earliestShipDate" "AttributeValue":"1716985920" } ]} } } ], "CartToken": null, "MerchantCartToken": "21531332-b15f-4640-ad5e-60887271a89a", "UserDetails": { "UserId": 12345, "AddressDetails": [{ "UserId": 12345, "FirstName": "Test", "LastName": "Test-e", "Phone1": "01234567", "Email": "[email protected]", "Address1": "2-4 Test St", "City": "Alexandria", "Zip": "2015", "CountryCode": "AU", "IsShipping": true, "IsBilling": true, "IsDefaultShipping": true, "IsDefaultBilling": true } ] }, "Discounts": [], "VATRegistration": { "VatRegistrationNumber": null, "DoNotChargeVAT": false }, "rateData": "bkep2SfLA8VXnA3+mU1e16u5InvGPYAmwm7RpmXveyU=","IsMoto":1} =" }