Merchant REST API
ClientApplyLoyaltyVouchers (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.
Use this method to validate the Loyalty Vouchers selected by the user from the list that has been provided in the loyaltyVouchersList argument of the SendCart
API call for the current user’s checkout page. This method can only be executed from within the context of the current user’s client session. Validates Loyalty Vouchers and applies them to the current user’s cart if all the vouchers in the list are valid and applicable.
If at least one Loyalty Voucher in the list is invalid,
Merchant.ResponseInfo.Success
is set to FALSE.If all Loyalty Vouchers are valid, the Merchant’s server should re-calculate the cart pricing and execute before returning a response, the
SendCart
API call with theCartToken
argument value returned from the previous call toSendCart
for the current user.
Method/URL
https://www.merchant-site-domain.com/ClientApplyLoyaltyVouchers
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| Object Merchant.CartAction | Delineates what action to perform with the cart data. | Yes |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Describes the response to the API call. In case of an error, indicates the error. |
Objects for ClientApplyLoyaltyVouchers API
Examples
Request
{ "LoyaltyVouchers":["123456","123467"] }
GetCheckoutCartInfo (Global-e to Merchant)
The GetCheckoutCartInfo API retrieves cart information for international checkout processing. This API:
Is triggered when the cart page loads or when a checkout attempt is made
Only returns products that are in stock
Requires proper cart token validation
Is part of Global-e's extensions (custom integration only)
This method is called from a Global-e server with the cart token rendered in a cookie or HTML.DOM. The client's session calculates the price totals. The GetCheckoutCartInfo API returns all cart contents, including customer information for logged-in customers
This API only returns products that are in stock. If special handling is required for stock validation on your side, for products in the basket (for example, calls to an external system), Global-e can specify an additional URL for this method, to indicate that stock validation is specifically required.
If the cart data is unavailable, the checkout will not open and an error message will appear in the browser development console.
The GetCheckoutCartInfo
API is only triggered upon the cart page loading, or when a checkout attempt is made.
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 in required.
Usage
Displays totals on the basket page
Opens the checkout process
Validates order (SendOrderToMerchant)
Security Requirements
Client-side: Session and Cart token (present in the request URL parameters)
Server-side: For both GET and POST:
Cart token - Request URL parameter (required)
Custom parameter - Request URL parameter (optional)
Custom header (optional)
IP whitelist (optional)
HTTP Basic Authentication (optional)
JWT (optional)
Additional methods available with POST only:
OrderID - In the request payload
Merchant GUID - In request payload (required)
Retry Logic
None. The GetCheckoutCartInfo API is only triggered upon the cart page loading, or when a checkout attempt is made. If the GetCheckoutCartInfo request fails to execute on the cart page, the international cart totals will not be calculated or displayed there. If the GetCheckoutCartInfo request fails on the checkout, the checkout will not open.
Method/URL
Client-side: GET
Server-side: GET
/ POST
(default GET
). Global-e can configure your preference.
GET https://www.merchant-site-domain.com/get-checkout-cart-info-url POST https://www.merchant-site-domain.com/get-checkout-cart-info-url
Parameters
Request
Requests can contain more parameters than listed.
Name | Type | Description | Mandatory |
---|---|---|---|
| String | 2-char ISO code for the country to which shipped | No |
| String | 3-char currency code for the country to which shipped | No |
| String | Identifier used for the cart by the Merchant’s site | No |
Response
The GetCheckoutCartInfo
API returns all cart contents, including customer information for logged-in customers.
Note
Some values are encoded and require the merchant to decode them, for example URLs, addresses, emails, and phone numbers.
Name | Type | Description |
---|---|---|
| Class CheckoutCartInfo | Retrieves cart information |
Objects for GetCheckoutCartInfo API
Examples
Response Sample 1
Response contains CheckoutCartInfo class
{ "productsList": [{ "ProductCode": "9632261340000", "ProductGroupCode": "9632261_c340000", "CartItemId": "6601", "ParentCartItemId": "", "CartItemOptionId": "", "Name": "name of product", "Description": "product description", "Keywords": "product keywords", "URL ": "product page url", "GenericHSCode ": "", "OriginCountryCode": "CHN", "Weight": 0.0, "Height": 0, "Width": 0, "Length": 0, "Volume": 0, "ImageURL": "", "ImageHeight": 533, "ImageWidth": 414, "IsFixedPrice": "true", "ListPrice": null, "OriginalListPrice": 20.0000, "SalePrice": 0.0, "SalePriceBeforeRounding": 0.0, "OriginalSalePrice": 20.0000, "OrderedQuantity": 2, "DeliveryQuantity": 2, "IsBlockedForGlobalE": false, "VATRateType": "", "LocalVATRateType": "", "Brand": { "BrandCode": "7", "Name": "Brand2" }, "Categories": null, "Attributes": [{ "AttributeCode": "26", "Name": "26", "AttributeTypeCode": "size" }, { "AttributeCode": "Geranium Red/Cut Out", "Name": "Geranium Red/Cut Out", "AttributeTypeCode": "color" } ], } ], "shippingDetails": { "UserId": "", "UserIdNumber": "", "UserIdNumberType": { "UserIdNumberTypeCode": null, "Name": "Shipping" }, "FirstName": "", "LastName": "", "MiddleName": "", "Salutation": "", "Phone1": "", "Phone2": "", "Fax": "", "Email": "", "Address1": "", "Address2": "", "City": "", "StateOrProvince": "", "StateCode": "", "Zip": "", "CountryCode": "", "CountryName": "" }, "billingDetails": { "UserId": "", "UserIdNumber": "", "UserIdNumberType": { "UserIdNumberTypeCode": null, "Name": "Billing" }, "FirstName": "", "LastName": "", "MiddleName": "", "Salutation": "", "Phone1": "", "Phone2": "", "Fax": "", "Email": "", "Address1": "", "Address2": "", "City": "", "StateOrProvince": "", "StateCode": "", "Zip": "", "CountryCode": "", "CountryName": "" }, "discountsList": [{ "OriginalDiscountValue": 10.0000, "DiscountType": "percentage", "Name": "discount name", "Description": "", "DiscountCode": null, "ProductCartItemId": 6601, "CouponCode": null } ] }
Response Sample 2: Dynamic Prices
{ "productsList": [{ "CartItemId": "676106", "ProductCode": "676106", "ProductGroupCode": "CS16577", "Name": "+Warmers", "Description": "Product List Description", "IsFixedPrice": false, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https://www.mystore.co.uk/product/[myproduct]", "Volume": 0.12, "Weight": 0.08, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 0 }, "OriginalSalePrice": 29.17, "Categories": [{ "CategoryCode": 161, "Name": "Cycle Clothing > Armwarmers" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 2, "Name": "Black" }, { "AttributeTypeCode": "size", "AttributeCode": 869, "Name": "M" } ], "OriginalListPrice": 35, "ImageURL": "https://www.mystore.co.uk/product-media/[myproductimpage.jpg]", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 38, "Name": "Castelli" }, "SalePrice": 0, "ListPrice": 0, "ProductClassCode": "expensive_warmers" }, { "CartItemId": "678197", "ProductCode": "678197", "ProductGroupCode": "7MESH-1507", "Name": "Resistance Jacket", "Description": "With its ...... short or long sleeve.", "IsFixedPrice": false, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https:\/\/www.mysite.co.uk\/item\/7Mesh\/Jacket\/EAM", "Volume": 1, "Weight": 0.115, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 20 }, "OriginalSalePrice": 150, "Categories": [{ "CategoryCode": 151, "Name": "Cycle Clothing > Jacket Wind" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 3, "Name": "Blue" }, { "AttributeTypeCode": "size", "AttributeCode": 367, "Name": "M" } ], "OriginalListPrice": 180, "ImageURL": "https:\/\/dbyvw4efi.cloudfront.net\Jacket-blue.jpg", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 705, "Name": "7Mesh" }, "SalePrice": 0, "ListPrice": 0 } ], "discountsList": [{ "OriginalDiscountValue": 3.398, "DiscountType": null, "Name": "GLOBALE20", "Description": null, "DiscountCode": "GLOBALE20", "ProductCartItemId": null, "CouponCode": "GLOBALE20", "CalculationMode": 1, "DiscountValue": 0 } ], "billingDetails": { "UserId": "1144404", "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "ISR", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "" }, "shippingDetails": { "UserId": "1144404", "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "winer", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "ISR", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "" } }
Response Sample 3: Fixed Prices
{ "productsList": [{ "CartItemId": "676106", "ProductCode": "676106", "ProductGroupCode": "CS16577", "Name": "N+ Warmers", "Description": "The Warmers .... and water resistance.", "IsFixedPrice": true, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https:\/\/www.mysite.co.uk\/Warmers\/HOG", "Volume": 0.12, "Weight": 0.08, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 20 }, "OriginalSalePrice": 0, "VATRateType": { "VATRateTypeCode": "vat10.5", "Rate": 10.5 }, "Categories": [{ "CategoryCode": 161, "Name": "Cycle Clothing > Warmers" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 2, "Name": "Black" }, { "AttributeTypeCode": "size", "AttributeCode": 869, "Name": "M" } ], "OriginalListPrice": 0, "ImageURL": "https:\/\/offpi.cloudfront.net\/Warmer.jpg", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 38, "Name": "BandNamei" }, "SalePrice": 120, "ListPrice": 120, "ProductClassCode": "expensive_warmers" }, { "CartItemId": "678197", "ProductCode": "678197", "ProductGroupCode": "7MESH-1507", "Name": "Resistance Jacket", "Description": "With its .... your short or long sleeves.", "IsFixedPrice": true, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https:\/\/www.mysite.co.uk\/Jacket\/JAM", "Volume": 1, "Weight": 0.115, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 20 }, "OriginalSalePrice": 0, "Categories": [{ "CategoryCode": 151, "Name": "Cycle Clothing > Jacket Wind" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 3, "Name": "Blue" }, { "AttributeTypeCode": "size", "AttributeCode": 367, "Name": "M" } ], "OriginalListPrice": 0, "ImageURL": "https:\/\/offpi.cloudfront.net\/Jacket-blue.jpg", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 705, "Name": "Mesh" }, "SalePrice": 180, "ListPrice": 150 } ], "discountsList": [{ "OriginalDiscountValue": 0, "DiscountType": null, "Name": "GLOBALE20", "Description": null, "DiscountCode": "GLOBALE20", "ProductCartItemId": null, "CouponCode": "GLOBALE20", "CalculationMode": 3, "DiscountValue": 50 } ], "billingDetails": { "UserId": "1144404", "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "ISR", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "" }, "shippingDetails": { "UserId": "1144404", "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "ISR", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "" } }
Response Sample 4: Multi Addresses
{ "productsList": [{ "CartItemId": "676106", "ProductCode": "676106", "ProductGroupCode": "CS16577", "Name": "N+ Warmers", "Description": "The <a href=\"https:\/\/www.mysite.co.uk\/brand\/... and water resistance.", "IsFixedPrice": true, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https:\/\/www.mysite.co.uk\/item\/Warmers\/HOG", "Volume": 0.12, "Weight": 0.08, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 21 }, "OriginalSalePrice": 0, "Categories": [{ "CategoryCode": 161, "Name": "Cycle Clothing > Warmers" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 2, "Name": "Black" }, { "AttributeTypeCode": "size", "AttributeCode": 869, "Name": "M" } ], "MetaData": { "Attributes": [{ "AttributeKey": "Name", "AttributeValue": "Alex" } ] }, "OriginalListPrice": 0, "ImageURL": "https:\/\/offpi.cloudfront.net\/Warmer.jpg", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 38, "Name": "BrandName" }, "SalePrice": 50, "ListPrice": 123, "ProductClassCode": "expensive_warmers" }, { "CartItemId": "678197", "ProductCode": "678197", "ProductGroupCode": "7MESH-1507", "Name": "Resistance Jacket", "Description": "With its ... your short or long sleeve.", "IsFixedPrice": false, "IsBlockedForGlobalE": false, "OrderedQuantity": 1, "URL": "https:\/\/www.mysite.co.uk\/Jacket\/JAM", "Volume": 1, "Weight": 0.115, "LocalVATRateType": { "VATRateTypeCode": "NORMAL", "Rate": 20 }, "OriginalSalePrice": 150, "Categories": [{ "CategoryCode": 151, "Name": "Cycle Clothing > Jacket" }, { "CategoryCode": "WORLDWIDE", "Name": "WORLDWIDE" } ], "Attributes": [{ "AttributeTypeCode": "colour_or_flavour", "AttributeCode": 3, "Name": "Blue" }, { "AttributeTypeCode": "size", "AttributeCode": 367, "Name": "M" } ], "OriginalListPrice": 180, "ImageURL": "https:\/\/offpi.cloudfront.net\/Jacket-blue.jpg", "ImageHeight": 145, "ImageWidth": 145, "Brand": { "BrandCode": 705, "Name": "Mesh" }, "SalePrice": 0, "ListPrice": 0 } ], "discountsList": [{ "OriginalDiscountValue": 0, "DiscountType": null, "Name": "GLOBALE20", "Description": null, "DiscountCode": "GLOBALE20", "ProductCartItemId": "676106", "CouponCode": "GLOBALE20", "CalculationMode": 3, "DiscountValue": 3.398 } ], "userDetails": { "UserId": "1144404", "AddressDetails": [{ "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "IL", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "", "IsShipping": true, "IsBilling": false, "IsDefaultShipping": true, "IsDefaultBilling": false, "AddressBookId": 111 }, { "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe", "Address1": "basel 25", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "IL", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "", "IsShipping": false, "IsBilling": true, "IsDefaultShipping": false, "IsDefaultBilling": true, "AddressBookId": 222 }, { "Email": "[email protected]", "Salutation": "", "FirstName": "john", "LastName": "doe3", "Address1": "basel 253", "Address2": "", "City": "petah tikva", "StateOrProvince": "", "Zip": "11223344", "CountryCode": "IL", "CountryName": "Israel", "Phone1": "0000000000", "Phone2": "", "IsShipping": true, "IsBilling": true, "IsDefaultShipping": false, "IsDefaultBilling": false, "AddressBookId": 333 } ] }, "allowMailsFromMerchant": true }
NotifyOrderRefund (Global-e to Merchant)
The NotifyOrderRefund method notifies the merchant about Global-e initiated refunds issued to the shopper.
If implemented on the merchant’s site, the Global‑e servers post the information about customer refunds, in cases where such refunds are initiated on the Global‑e side.
Method/URL
https://www.merchant-site-domain/order-refund-url
Parameters
Request
Requests can contain more parameters than listed.
Name | Type | Description | Mandatory |
---|---|---|---|
order | Object Merchant.OrderRefund | Contains information about order refunds. | 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 |
---|---|---|---|
Merchant.ResponseInfo | Object Merchant.ResponseInfo | Provides response data regarding the API call. |
Objects for NotifyOrderRefund API
Example
Request
{ "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "MerchantOrderId": "14123332", "Products": [{ "CartItemId": 12365, "RefundQuantity": "3", "OriginalRefundAmount": "114.5300", "RefundAmount": "170.1000", "RefundReason": { "OrderRefundReasonCode": "DAMAGED-ITEM-CODE", "Name": "Damaged Item" }, "RefundComments": "Fully refunded order" } ], "OrderId": "GE69488861GB", "RefundId": 789, "RMANumber": 6543, "CurrencyCode": “CAD”, "OriginalCurrencyCode": “USD”, "TotalRefundAmount": "170.10", "RefundReason": { "OrderRefundReasonCode": "DAMAGED-ITEM-CODE", "Name": "Damaged Item" }, "RefundComments": "Fully refunded order", "OriginalTotalRefundAmount": "114.53", "ServiceGestureAmount": "0.00", "WebStoreCode": null }
PerformOrderPayment (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.
Posts order payment details to the Merchant's site and perform the payment.
Only order.OrderId
and order.PaymentDetails
classes are mandatory for this method. For Mixed orders, "Subs
" is mandatory.
SecurityRequirements
Merchant GUID - In request payload (required)
Custom header (optional)
IP whitelist (optional)
HTTP Basic Authentication (optional)
JWT (optional)
Retry Logic
There is no retry upon a merchant failure response or timeout. The timeout period is 5 minutes and this cannot be adjusted. Requests that fail to initiate from Global-e side will trigger an alert to the Global-e NOC team for manual review. Merchant failure responses or timeouts will trigger an alert to the Global-e NOC team for manual review. Requests that fail to initiate from Global-e side will trigger a retry once a minute for up to 3 attempts after which an alert will trigger for manual review.
Method/URL
POST https://www.merchant-site-domain.com/order-payment-only-url
Parameters
Request
Requests can contain more parameters than listed.
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 Merchant.Order |
| Yes |
Objects for PerformOrderPayment API
Examples
Request (
{ "OrderId": "00010000100000000020", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "PaymentDetails": { "OwnerFirstName": "Nir", "OwnerLastName": "Debbi", "OwnerName": "GlobalE", "CardNumber": "0000-0000-0000-0000", "CVVNumber": "000", "PaymentMethodName": "Visa", "PaymentMethodCode": "VI", "PaymentMethodTypeCode": "cc", "ExpirationDate": "2016-10-31", "CountryName": "Israel", "CountryCode": "IL", "StateOrProvince": "", "City": "Petach Tikva", "Zip": "12345", "Address1": "Kiryat Arye", "Address2": "", "Phone1": "", "Phone2": "", "Fax": "", "Email": "" } }
Response Example
{ "AllowMailsFromMerchant":false, "AllowSMSFromMerchant":null, "AllowDirectCommunicationFromMerchant":null, "ReservationRequestId":null, "ClearCart":false, "CurrencyCode":null, "Customer":{ "EmailAddress":null, "IsEndCustomerPrimary":false, "SendConfirmation":false }, "CustomerComments":null, "Discounts":[ ], "DoNotChargeVAT":false, "FreeShippingCouponCode":null, "IsFreeShipping":false, "IsSplitOrder":false, "LoyaltyCode":null, "LoyaltyPointsEarned":null, "LoyaltyPointsSpent":null, "Markups":[ ], "OriginalMerchantTotalProductsDiscountedPrice":0.0, "OTVoucherAmount":null, "OTVoucherCode":null, "OTVoucherCurrencyCode":null, "InitialCheckoutCultureCode":null, "CultureCode":null, "HubId":null, "HubCode":null, "PrimaryShipping":{ "Address1":null, "Address2":null, "AddressBookId":null, "City":null, "Company":null, "CountryCode":null, "CountryCode3":null, "CountryName":null, "Email":null, "Fax":null, "FirstName":null, "LastName":null, "MiddleName":null, "Phone1":null, "Phone2":null, "Salutation":null, "StateCode":null, "StateOrProvince":null, "Zip":null, "CollectionPointId":null, "AddressBookName":null, "CustomerTaxId":null }, "Products":[ ], "RoundingRate":0.0, "SameDayDispatch":false, "SameDayDispatchCost":0.0, "SecondaryShipping":{ "Address1":null, "Address2":null, "AddressBookId":null, "City":null, "Company":null, "CountryCode":null, "CountryCode3":null, "CountryName":null, "Email":null, "Fax":null, "FirstName":null, "LastName":null, "MiddleName":null, "Phone1":null, "Phone2":null, "Salutation":null, "StateCode":null, "StateOrProvince":null, "Zip":null, "CollectionPointId":null, "AddressBookName":null, "CustomerTaxId":null }, "ShippingMethodCode":null, "ShipToStoreCode":null, "UrlParameters":null, "IsReplacementOrder":false, "OriginalOrder":null, "TotalDutiesAndTaxesPrice":0.0, "CCFPrice":0.0, "UserId":null, "GiftCards":[ ], "PreferredCultureCode":null, "ShippingVATRate":null, "OrderPaymentMethods":[ { "PaymentMethodId":1, "PaymentMethodName":"Visa", "IsGiftCard":false, "GiftCardFields":null, "PaidAmountInCustomerCurrency":393.5600, "PaidAmountInMerchantCurrency":235.74993308058803207162312511, "PaymentMethodTypeCode":"1", "PaymentMethodTypeName":"Credit Card" }], "CustomerDTBreakdown":null, "MerchantDTBreakdown":null, "TotalDutiesPaidByCustomerPrice":null, "CookieConsent":0, "IsMoto":false, "ModifiedProduct":null, "TaxCalculationRule":"CIF", "TotalValueForCustoms":393.5600, "USSalesTax":0.0, "ImporterDetails":null, "PaymentDetails":{ "Address1":"200 west 41st street", "Address2":"9th floor", "CardNumber":null, "City":"New York", "CountryCode":"US", "CountryCode3":"USA", "CountryName":"United States", "CVVNumber":null, "Email":"[email protected]", "ExpirationDate":"2040-09-22", "Fax":null, "OwnerFirstName":"Global-e", "OwnerLastName":"US Inc.", "OwnerName":"Global-e US Inc.", "PaymentMethodCode":"OT", "PaymentMethodName":"Undefined", "PaymentMethodTypeCode":"globaleintegration", "Phone1":"+1 (212) 634-3952", "Phone2":null, "StateCode":"NY", "StateOrProvince":"New York", "Zip":"10036" }, "PrimaryBilling":{ "Address1":"t", "Address2":null, "AddressBookId":null, "City":"t", "Company":null, "CountryCode":"NZ", "CountryCode3":"NZL", "CountryName":"New+Zealand", "Email":"[email protected]", "Fax":null, "FirstName":"FirstName", "LastName":"LastName", "MiddleName":null, "Phone1":"2125551212", "Phone2":null, "Salutation":null, "StateCode":null, "StateOrProvince":null, "Zip":"2345", "CollectionPointId":null, "AddressBookName":null, "CustomerTaxId":null }, "SecondaryBilling":{ "Address1":"200 west 41st street", "Address2":"9th floor", "AddressBookId":null, "City":"New York", "Company":"GlobalE", "CountryCode":"US", "CountryCode3":"USA", "CountryName":"United States", "Email":"[email protected]", "Fax":null, "FirstName":"Global-e", "LastName":"US Inc.", "MiddleName":null, "Phone1":"+1 (212) 634-3952", "Phone2":null, "Salutation":null, "StateCode":"NY", "StateOrProvince":"New York", "Zip":"10036", "CollectionPointId":null, "AddressBookName":null, "CustomerTaxId":null }, "CartHash":"3A29A654B1A5DD8D758D19C827B69E83", "CartToken":null, "GlobalECartToken":null, "CartId":"f9847639-95e8-4e75-b198-9031a205e001:384880634", "DiscountedShippingPrice":221.15, "InternationalDetails":{ "ConsignmentFee":0.0000, "CurrencyCode":"NZD", "DeliveryDaysFrom":9, "DeliveryDaysTo":15, "DiscountedShippingPrice":369.1900, "DutiesGuaranteed":false, "OrderTrackingNumber":null, "OrderTrackingUrl":"https%3a%2f%2fwww.bglobale.com%2fOrder%2fTrack%2fmZz5%3fOrderId%3dGE01812420US%26ShippingEmail%3dtest%40test.com", "OrderWaybillNumber":null, "PaymentMethodCode":"1", "PaymentMethodName":"Visa", "RemoteAreaSurcharge":0.0000, "SameDayDispatchCost":0.0000, "ShippingMethodCode":"40049745", "ShippingMethodName":"DHL api Express Worldwide", "ShippingMethodTypeCode":"Express", "ShippingMethodTypeName":"Express Courier (Air)", "SizeOverchargeValue":17.0000, "TotalCCFPrice":0.0000, "TotalDutiesPrice":0.000000000, "TotalPrice":393.56, "TotalShippingPrice":369.1900, "TransactionCurrencyCode":"NZD", "TransactionTotalPrice":393.5600, "ParcelsTracking":null, "CardNumberLastFourDigits":null, "ExpirationDate":null, "ShippingVATRate":0.0000, "CashOnDeliveryFee":0.0, "CustomerDTBreakdown":null, "MerchantDTBreakdown":null, "DeliveryDateFrom":"25.03", "DeliveryDateTo":"04.04", "ShipmentLocation":null, "ShipmentStatusUpdateTime":null, "ShippingMethodStatusCode":"Undefined", "ShippingMethodStatusName":"undefined" }, "MerchantGUID":"12345678-1234-1234-1234-123456789012", "MerchantOrderId":"123456789", "OrderId":"GE01812420US", "PriceCoefficientRate":1.150000, "StatusCode":"N/A", "WebStoreCode":"en-nz", "WebStoreInstanceCode":"en-nz" }
RedeemGiftCard (Global-e to Merchant)
The RedeemGiftCard API sends the amount of the used card balance. This information is saved on your platform.
Add the GiftCardData.RedeemTransactionId
for each gift card during this call.
Method/URL
https://www.merchant-site-domain.com/redeem-gift-card-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
RedeemGiftCardRequest | Object RedeemGiftCardRequest | Contains information regarding gift card redemption. | Yes |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
RedeemGiftCardResponse | Object RedeemGiftCardResponse | Provides details about response to API call for gift card redemption. |
Objects for RedeemGiftCard API
Examples
Request
{ "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "ShippingCountryCode": "IL", "Cards": [{ "CardId": 2864, "BalanceInGiftCardCurrency": 365.930000, "BalanceInCustomerCurrency": 1286.210000, "GiftCardCurrencyCode": "USD", "CustomerCurrencyCode": "ILS", "BalanceUsedInCardCurrency": 94.910000, "BalanceUsedInCustomerCurrency": 333.590000, "CardFields": { "CardId": "111111" } } ], "OrderId": " GE927127", "MerchantCartToken": "cf270ce6b2d4ce6d2d882536b8741a01" }
Response
{ "Cards": [{ "CardId": 2864, "BalanceInGiftCardCurrency": 365.93, "BalanceInCustomerCurrency": 1286.21, "GiftCardCurrencyCode": "USD", "CustomerCurrencyCode": "ILS", "BalanceUsedInCardCurrency": 94.91, "BalanceUsedInCustomerCurrency": 333.59, "RedeemTransactionId": 2, "CardFields": { "CardId": "111111" } } ], "ErrorCode": null, "ErrorText": null }
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 ofGiftCardData.BalanceUsedInCardCurrency
GiftCardData.RefundedBalanceInCustomerCurrency
– must not exceed the provided value ofGiftCardData.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
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" }
RemoveRestrictedProducts (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 removes restricted products from the merchant cart; it notifies merchants that restricted products were removed from the cart, then merchants must also update the cart on the merchant side.
Method/URL
https://www.merchant-site-domain.com/remove-restricted-products-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
Merchant.RemoveRestrictedProductsRequest | Contains information related to a request to remove a restricted product. | Yes |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
Merchant.RemoveRestrictedProductsResponse | Provides details about response to API call for removal of a restricted product. |
Objects for RemoveRestrictedProducts API
Examples
Request
{ "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "CartToken": "d3b9d91b-cbc9-4485-9f37-b0490c419338", "CartId": "37296D5PJE", "UserId": null, "CountryCode": "VN", "CurrencyCode": "VND", "WebStoreCode": null, "WebStoreInstanceCode": null, "RemovedProductCodes": ["1601893OPK0XS"] }
Response
{"IsSuccess": true}
SendAdditionalRequiredDocumentsToMerchant (Global-e to Merchant)
SendAdditionalRequiredDocumentsToMerchant
( SendAdditionalRequiredDocumentsToMerchantRequest
request)
Posts the required shipping documents of the order to the Merchant’s site
This notification informs the Merchant that the documents previously listed in SendorderToMerchant
notification (under AdditionalRequiredDcouments), initiated by calling CreateAdditionalRequiredDcouments
, are ready.
The document's content is included in this notification.
Security:
IP whitelist
Secret GUID
Authorization header
Method/URL
POST https://www.merchant-site-domain.com/send-additional-required-documents-url
Examples
Request:
{ "OrderId": "Sample order id", "MerchantOrderId": "Sample order id from the merchant’s system", "CountryCode": "US", "AdditionalRequiredDocuments": [ { "TrackingNumber" "98789723874839", "DocumentData": "base 64 string", "URL": "URL do download document", "DocumentTypeCode": "11", "DocumentTypeName": "EAD", "DocumentExtension": "pdf", "DocumentReference": "24DE85123822923B8", "CreationDateTime": "2024-01-30T10:55:21" } ] }
Response:
{ "StatusCode": "200", "Success": "true", "Message": "...", "ErrorCode": "...", "ErrorText": "..." }
SendOrderToMerchant (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 posts the new order or updates the existing order on the merchant’s site.
When implementing a Global-e extension or plug-in, this method is required to create the customer order in the merchant’s system, clear the user’s basket, and optionally, reserve the inventory.
If
order.PaymentDetails
are provided, this method also performs the payment and returns the currency and amount actually charged in theMerchant.ResponseInfo
.If additional shipping documents are required for merchants that are shipping the order themselves, then it is indicated in
AdditionalRequiredDocuments
. In that case, the merchant should delay the fulfillment until the documents are ready and provided to the merchant in theSendAdditionalRequiredDocumentsToMerchant
webhook.
Security Requirements
Merchant GUID - In request payload (required)
Custom header (optional)
IP whitelist (optional)
HTTP Basic Authentication (optional)
JWT (optional)
Retry Logic
There is no retry upon a merchant failure response or timeout. The timeout period is 5 minutes but can be adjusted if necessary. Merchant failure responses or timeouts will trigger an alert to the Global-e NOC team for manual review. Requests that fail to initiate from Global-e side will trigger a retry once a minute for up to 3 attempts, after which an alert will trigger for manual review.
Method/URL
POST https://www.merchant-site-domain.com/order-update-create-url
Parameters
Request
Requests can contain more parameters than listed.
Name | Type | Description | Mandatory |
---|---|---|---|
order | Object Merchant.Order | Information about the order. |
Response
Note
Some values are encoded and require the merchant to decode them, for example URLs, addresses, emails, and phone numbers.
Name | Type | Description | Mandatory |
---|---|---|---|
ResponseInfo | Object Merchant.ResponseInfo | Indicates if an API call was successful or not and why. |
Objects for SendOrderToMerchant API
Examples
Request Sample 1
{ "ClearCart": true, "UserId": null, "CurrencyCode": "ILS", "Products": [{ "Attributes": [{ "AttributeKey": "color", "AttributeValue": "GREY" } ], "ProductName":"Ribbed Modal Tank Flare Pants Set", "Sku": "7290012491726", "Price": 21.55, "Quantity": 8, "VATRate": 18, "InternationalPrice": 4.84, "CartItemId": "11007", "Brand": null, "Categories": [] } ], "Customer": { "EmailAddress": "[email protected]", "IsEndCustomerPrimary": false, "SendConfirmation": false }, "PrimaryShipping": { "FirstName": "GlobalE", "LastName": "GlobalE", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "21/D, Yegi'a Kapayim st. Yellow building - Floor 1", "Address2": "Test Address2", "City": "Petach Tikva", "StateCode": "NN", "StateOrProvince": null, "Zip": "4913020", "Email": "[email protected]", "Phone1": " 972 73 204 1384", "Phone2": "Test Phone2", "Fax": "Test Fax", "CountryCode": "IL", "CountryName": "Israel", "CollectionPointId": "030749" }, "SecondaryShipping": { "FirstName": "John", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "Amishav%2024", "Address2": null, "City": "Paris", "StateCode": null, "StateOrProvince": null, "Zip": "66666", "Email": "John.Smith%40global-e.com", "Phone1": "98756344782", "Phone2": null, "Fax": null, "CountryCode": "FR", "CountryName": "France", "CollectionPointId": null }, "ShippingMethodCode": "globaleintegration_standard", "Discounts": [{ "Name": "Shipping discount provided by globale", "Description": "Auto calculated according to products", "Price": 35.31, "DiscountType": 2, "VATRate": 18, "CouponCode": null, "InternationalPrice": 6.58 "MetaData":"" } ], "InternationalDetails": { "CurrencyCode": "EUR", "TotalPrice": 64.88, "TransactionCurrencyCode": "EUR", "TransactionTotalPrice": 64.88, "TotalShippingPrice": 32.74, "TotalDutiesPrice": 0, "ShippingMethodCode": "2", "ShippingMethodName": "EMS", "PaymentMethodCode": "1", "PaymentMethodName": "Visa", "DutiesGuaranteed": false, "OrderTrackingNumber": null, "OrderTrackingUrl": "http://www.israelpost.co.il/itemtrace.nsf/mainsearch?openform", "OrderWaybillNumber": null, "OrderWaybillUrl": null, "ShippingMethodStatusCode": "0", "ShippingMethodStatusName": "undefined", "CardNumberLastFourDigits": "7854", "ExpirationDate": "2023-06-30", "TotalVATAmount": 11.14 }, "PaymentDetails": null, "PrimaryBilling": { "FirstName": "GlobalE", "LastName": "GlobalE", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "21/D, Yegi'a Kapayim st. Yellow building - Floor 1", "Address2": null, "City": "Petach Tikva", "StateCode": null, "StateOrProvince": null, "Zip": "4913020", "Email": "[email protected]", "Phone1": " 972 73 204 1384", "Phone2": null, "Fax": " 972 73 204 1386", "CountryCode": "IL", "CountryName": "Israel", "CollectionPointId": null }, "SecondaryBilling": { "FirstName": "John", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "Amishav%2024", "Address2": null, "City": "Paris", "StateCode": null, "StateOrProvince": null, "Zip": "66666", "Email": "John.Smith%40global-e.com", "Phone1": "972500000", "Phone2": null, "Fax": null, "CountryCode": "FR", "CountryName": "France", "CollectionPointId": null }, "OrderId": "GE927127", "StatusCode": "N/A", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "CartId": "9936", "MerchantOrderId": null, "PriceCoefficientRate": 1, "OrderCreationSource": 0, "IsMoto": true, "ModifiedProduct": "G007163737" "AdditionalRequiredDocuments": [ { "DocumentTypeCode": "11 (value from enum)", "DocumentTypeName": "EAD", }, ] }
Request Sample 2
{ "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "OrderId": "GE12345678GB", "CartId": "56004460", "UserId": "cecofzj348wdhbr98UbNNDa", "CurrencyCode": "GBP", "PriceCoefficientRate": 1.340000, "RoundingRate": 0.8774285714285714285714285714, "UrlParameters":"[{\"Key\":\"associateOrder\",\"Value\":\"false\"}}], "OrderCreationDate":"2024-05-29T12:33:08.443", "EffectiveFXRate":0.944130024000, "WebStoreInstanceCode": "GlobalEDefaultStoreInstance", "DiscountedShippingPrice": 8.77, "DoNotChargeVAT": false, "AllowMailsFromMerchant": true, "CustomerComments": null, "IsFreeShipping": false, "FreeShippingCouponCode": null, "ShipToStoreCode": null, "InternationalDetails": { "CurrencyCode": "USD", "TotalPrice": 38.00, "TransactionCurrencyCode": "USD", "TransactionTotalPrice": 38.0000, "TotalShippingPrice": 15.3600, "DiscountedShippingPrice": 10.0000, "DutiesGuaranteed": false, "TotalDutiesPrice": 0.0000, "PaymentMethodCode": "1", "PaymentMethodName": "Visa", "ShippingMethodCode": "608", "ShippingMethodName": "DHL Express Worldwide", "ShippingMethodTypeCode": "Express", "ShippingMethodTypeName": "Express Courier (Air)", "PaymentTransactionReference":"89288", "DeliveryDaysFrom": 3, "DeliveryDaysTo": 4, "OrderTrackingNumber": null, "OrderTrackingUrl": "https%3a%2f%2fwww2.bglobale.com%2fOrder%2fTrack%2fmZyd%3fOrderId%3dGE4874348GB%26ShippingEmail%3djsmith%40merchant.com", "CardNumberLastFourDigits": "7854", "ExpirationDate": "2023-06-18" }, "Products": [{ "CartItemId": "10367295488044", "Sku": "2410016114", "Price": 30.7100, "Quantity": 1, "VATRate": 20.000000, "InternationalPrice": 35.0000, "RoundingRate": 0.8774285714285714285714285714, "IsBackOrdered": false, "BackOrderDate": null, "DiscountedPrice": 24.57, "InternationalDiscountedPrice": 28.0000, "GenericHSCode":"392800", "GiftMessage": null, "MetaData": { "Attributes": [{ "AttributeKey": "giftnotemessage", "AttributeValue": "Hello, world" }, { "AttributeKey": "giftnotefont", "AttributeValue": "FONTTYPE1" }, { "AttributeKey": "WRTY", "AttributeValue": "Warranty card" } ] } } ], "Discounts": [{ "DiscountType": 1, "Name": "20% off", "Description": "20% off all non-sale items.", "Price": 6.1400, "VATRate": 20.000000, "InternationalPrice": 7.0000, "CouponCode": "GO20", "DiscountCode": "Email_Sign_up-20%_off", "ProductCartItemId": "10367295488044", "LoyaltyVoucherCode": null }, { "DiscountType": 2, "Name": "Shipping discount for fixed price", "Description": "Shipping discount provided from fixed price range 24663", "Price": 4.7000, "VATRate": 20.000000, "InternationalPrice": 5.3600, "CouponCode": null, "DiscountCode": null, "ProductCartItemId": null, "LoyaltyVoucherCode": null } ], "PrimaryShipping": { "FirstName": "Jenny", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "12+E+11th+St", "Address2": null, "City": "New+York", "StateCode": "NY", "StateOrProvince": "New York", "Zip": "10003", "Email": "jsmith%40merchant.com", "Phone1": "0123456789", "Fax": null, "CountryCode": "US", "CountryCode3": "USA", "CountryName": "United States" }, "SecondaryShipping": { "FirstName": "GlobalE", "LastName": "East Midlands Airport", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "96a, Beverley Road", "Address2": "East Midlands Airport\r\nGE12345678GB", "City": "Derby", "StateCode": "NN", "StateOrProvince": null, "Zip": "DE74 2SA", "Email": "[email protected]", "Phone1": "01332 818723", "Fax": null, "CountryCode": "GB", "CountryCode3": "GBR", "CountryName": "United Kingdom" }, "PrimaryBilling": { "FirstName": "Jenny", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "12+E+11th+St", "Address2": null, "City": "New+York", "StateCode": "NY", "StateOrProvince": "New York", "Zip": "10003", "Email": "jsmith%40merchant.com", "Phone1": "0123456789", "Fax": null, "CountryCode": "US", "CountryCode3": "USA", "CountryName": "United+States" }, "SecondaryBilling": { "FirstName": "GlobalE", "LastName": "UK Limited", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "45 Leather Lane", "Address2": null, "City": "London", "StateCode": null, "StateOrProvince": null, "Zip": "EC1N 7TJ", "Email": "[email protected]", "Phone1": "+ 44 (0)808 258 0300", "Fax": "+ 44 (0)203 514 7171", "CountryCode": "GB", "CountryCode3": "GBR", "CountryName": "United Kingdom" }, "OrderPaymentMethods":[ { "PaymentMethodGuid":"23ATEM329IF9493", "IsGiftCard":false, "GiftCardFields":null, }], "AdditionalRequiredDocuments": [ { "DocumentTypeCode": "11", "DocumentTypeName": "EAD", } ] }
SendRMAToMerchant (Global-e to Merchant)
Use the SendRMAToMerchant API to send the Global‑e RMA number to the merchant. Sends MerchantReturn object to the merchant.
MerchantAppSetting
, SendRMAInfoToMerchantURI
must be set to turn on this feature.
Method/URL
POST https://www.merchant-site-domain.com/rma-info-to-merchant-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
merchantOrder | Object merchantOrder | Provides order return details. | |
merchantReturn | Object merchantReturn | Provides merchant return information. Includes the following information:
|
Return
Name | Type | Description | Mandatory |
---|---|---|---|
merchant.ResponseInfo | Object Merchant.ResponseInfo | Provides API call response info. |
Objects for SendRMAToMerchant API
Examples
Request Example
{ "OrderId": "GE24192321GB", "MerchantOrderId": "71144", "RMANumber": "223878", "ShipperName": "DHL", "ReturnTrackingNumber": "857854854778", "TrackingURL": "www.dhl.com/Tracking?TrackingNumber=857854854778", "CreatedBy": "Customer", "ReturnedProducts": [ { "SKU": "ProductD", "Name": "Blue jacket", "CartItemId": "2", "ReturnQuantity": 1, "ReturnReasonName": "Arrived too late", "MerchantReturnReasonCode": null, "MerchantReturnReasonName": null } ], "MerchantGUID": "7e3d5523-d86a-4c56-8f47-5a48b829e3b7", "CurrencyCode": "EUR", "ReturnShippingCost": 10.00 }
Response Example
{ "Success": "True", "Message": "success message", "Description": "success description" }
Sending Bulk Emails
Sending Bulk Emails (Merchant to Global-e)
Emails can now be sent to multiple addresses by issuing an API call providing order IDs and the email message type. Additionally, placeholders can be added to the mail message to dynamically add details to the email message content without code changes.
This API provides the following:
Allow the merchant to send CS emails (Bulk Emails) on a single API by providing a list of order IDs
Allow the merchant to specify the email address for sending the processing report
Allow merchant the option to specify the return address, default as configured for CS/FinOps
Monitor and log merchant actions
Store the action results report for performance and success level measurements.
Customize the email message template for full merchant customizations and look & feel
Prerequisites
The following is to be prepared Before issuing the API:
Select the email type and verify its template, from the existing types, or ask your CSM to create a template.
Specify the placeholders' name and value, if you plan to add them to the email message.
List the Order IDs that are the addressees of this mail.
Method/URL
POST https://{globale_api_domain}/emails
Parameters
Note
A text resource value refers to predefined placeholders and their related values. The placeholders and their values are defined in the Admin platform, with the prefix TR_. A value can be a Global-e default value or merchant-specific value. Refer to your CSM for all predefined TR_ placeholders, and for defining merchant-specific values.
Name | Type | Description | Mandatory |
---|---|---|---|
| String | Specifies the name of the email type and its related HTML template. | Yes |
| String | The mail address of the sender that the addressee sees. The default sender mail address is [email protected] or other mail specified by the merchant. | Yes |
| String | The merchant’s email address to receive the bulk sending report. | Yes |
| Array of Strings | The list of addressees, by their Order ID. | Yes |
| List <Placeholder> | A list of placeholders and their value source. Each Placeholder object contains:
| No |
Return Codes
The returned error codes are as follows:
Code | Description | |
---|---|---|
400 | The following descriptions can be returned:
|
Email Examples
Mail Message
In the following example, the Order ID is integrated into the email template, by adding the orderId placeholder.
![]() |
Note: When sending a list of Order IDs in the API request, each mail message will have the relevant ID for the mail recipient.
Results Report Email
The following report is received detailing the result of the bulk emails API, sent to inform of a delayed fulfillment of a single order ID.
![]() |
Example
Request
"orderIds": [ "orderIds": [ GE399999999GB""GE399999999GB" ], ], "placeholders": { "placeholders": { "{DelayReason}": "TR_OverloadDelayReason", "{DelayReason}": "TR_OverloadDelayReason", "{DelayDaysCount}": "2", "senderEmailAddress": "[email protected]", "emailTypeName": "Delayedfulfillment", "reportToEmailAddress": "[email protected]" } }
Response
{ "Processing is in progress. You will get an email after the process is complete." }
UpdateOrderShippingInfo (Global-e to Merchant)
Update
Merchant.Order
Updates the order's international shipping information on the Merchant site.
Only order.OrderId
and order.InternationalDetails
members are mandatory for this method.
Method/URL
https://www.merchant-site-domain.com/order-shipping-info-update-only-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
order | Object Merchant.Order | Object MerchantOrder contains details about the status of the order on the merchant's site. | Yes |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
ResponseInfo | Object Merchant.ResponInfo | Response details regarding API call. |
Objects for UpdateOrderShippingInfo API
Examples
Request
{ "OrderId": "00010000100000000020", "InternationalDetails": { "OrderTrackingNumber": "1265443", " OrderTrackingUrl": "http://www.somecarrier.com/?1265443" }, "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd" }
UpdateOrderStatus (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.
Updates order status of the order on the Merchant’s site. Only order.OrderId
and order.StatusCode
members are mandatory for this method.
When implementing a Global-e extension or plug-in, this method is required to support order cancellation when it is initiated on Global-e’s side. It can also be used for reporting other order status updates as they occur in the Global-e’s system, and reflect them in the Merchant’s system.
Method/URL
POST https://www.merchant-site-domain.com/order-status-update-only-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
orderStatus | Object MerchantOrder | Object MerchantOrder contains details about the status of the order on the merchant's site. | Yes |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
ResponseInfo | Object Merchant.ResponInfo | Response details regarding API call. |
Objects for UpdateOrderStatus
Example
Request
{ "OrderId": "00010000100000000020", "StatusCode": "canceled", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd" }
UpdateRMA
Call the UpdateRMA
API to set or update the MerchantRMANumber
and send an email to the customer.
Method/URL
https://{server_name}/Return/UpdateRMA?merchantGUID= F3BE2R-8546-FC38-90SJ-1C780SG8F90SBS
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
updateRMANumber | Object MerchantRMANumber | Provides API call response info. |
Return
Name | Type | Description | Mandatory |
---|---|---|---|
merchant.ResponseInfo | Object Merchant.ResponseInfo | Provides API call response info. |
Objects for SendRMAToMerchant API
Examples
Request
{ “OrderId”: ”12345”, (optional) “MerchantOrderId”: ”09876”, (optional) ”RMANumber”: ”852147”, ”MerchantRMANumber”: ”265646925” }
ValidateGiftCard (Global-e to Merchant)
The ValidateGiftCard
request sends the gift card data to the platform, gets the card amount, and makes sure that the card is valid.
ValidateGiftCard
is called when the user fills out all gift card fields on the checkout page.
Method/URL
https://www.merchant-site-domain.com/validate-gift-card-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
ValidateGiftCardRequest | Object ValidateGiftCardRequest | Provides information related to validating the gift card. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
ValidateGiftCardResponse | Object ValidateGiftCardResponse | Provides API call response info. |
Objects for ValidateGiftCard API
Examples
Request
{ "MerchantGUID": abcdabcd - abcd - abcd - abcd - abcdabcdabcd ", " ShippingCountryCode ":" UA ", " CardFields ":{" CardId ":" 111111 "}, " MerchantCartToken ":" 2c5c7b3db2ed101426cba38d9c534086 " }
Responses
For valid cards:
{ "IsValid": true, "Balance": 1000, "CurrencyCode": "GBP", "IsGlobalEGiftCard": false, "ErrorCode": null, "ErrorText": null }
For invalid cards:
{ "IsValid": false, "Balance": null, "CurrencyCode": null, "IsGlobalEGiftCard": false, "ErrorCode": null, "ErrorText": "Invalid Card" }
ValidateStock (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.
The Merchant Cart Validation checks basic cart validity and validates the product’s stock availability.
If a product line cart item listed in order.Products
does not have full stock availability for the specified quantity, this cart item is included in the AmendedProducts
array with an indication of the quantity actually available. If all items are in stock, the AmendedProducts
array is empty.
If required, the ValidateStock
API is called when the shopper is in the Global‑e checkout. If the AmendedProducts
array is not empty, the list of out-of-stock products is displayed to the shopper.
Note
In the GEM integration method, the GetCheckoutCartInfo
API may be reused for stock validation purposes.
Method/URL
https://www.merchant-site-domain.com/checkout-validate-cart-stock-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
order | Object Merchant.Order | Provides information related to the order. |
Request
Name | Type | Description | Mandatory |
---|---|---|---|
Merchant.StockValidationResponse | Provides information related to validating that stock exists. |
Objects for ValidateStock API
Examples
Request
{ "GlobalECartToken": "1da35dc3-cbe6-4cd8-81d6-ce433466d715", "PreferredCultureCode": null, "AuthToken": "34sdfdg43erfg43234fwsedfsdf423", "SessionId": "12345", "DateCreated": "0001-01-01T00:00:00", "CurrencyName": null, "Parcels": null, "AllowMailsFromMerchant": false, "AllowDirectCommunicationFromMerchant": false, "ClearCart": false, "UserId": null, "CurrencyCode": "ILS", "Products": [{ "Attributes": null, "Sku": "648340636", "Price": 157.7000, "PriceBeforeRoundingRate": null, "PriceBeforeGlobalEDiscount": null, "Quantity": 1, "VATRate": null, "CustomerVATRate": null, "InternationalPrice": 649.0000, "InternationalDiscountedPriceInMerchantCurrency": null, "CartItemId": "ci21000088", "ParentCartItemId": null, "CartItemOptionId": null, "HandlingCode": null, "GiftMessage": null, "RoundingRate": 0.0, "IsBackOrdered": false, "BackOrderDate": null, "DiscountedPrice": null, "InternationalDiscountedPrice": null, "ProductCodeSecondary": "MKC1120A~N~040~~NS", "Brand": null, "Categories": null, "ListPrice": 0.0, "InternationalListPrice": 0.0, "GenericHSCode": null, "DiscountedPriceForCustoms": 0.0, "InternationalDiscountedPriceForCustoms": 0.0, "IsGiftCard": false, "IsFixedPrice": true } ], "Customer": { "EmailAddress": null, "IsEndCustomerPrimary": false, "SendConfirmation": false }, "PrimaryShipping": { "FirstName": "sdfsdf", "LastName": "sdfsdf", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "asdasd+234", "Address2": "", "City": "asdasd", "StateCode": null, "StateOrProvince": null, "Zip": "1234567", "Email": "sdfsdf%40asdasd.com", "Phone1": "0000000000", "Phone2": null, "Fax": null, "CountryCode": "IL", "CountryCode3": null, "CountryName": null, "AddressBookId": null, "AddressBookName": null, "SaveAddress": false }, "SecondaryShipping": { "FirstName": "GlobalE", "LastName": "GE-UK@EMA-Norsk", "MiddleName": null, "Salutation": null, "Company": "", "Address1": "Building 436, Argosy Road", "Address2": "East Midlands Airport", "City": "Derby", "StateCode": "NN", "StateOrProvince": null, "Zip": "DE74 2SA", "Email": "[email protected]", "Phone1": "01332 818723", "Phone2": null, "Fax": null, "CountryCode": "GB", "CountryCode3": "GBR", "CountryName": "United Kingdom", "AddressBookId": null, "AddressBookName": null, "SaveAddress": false }, "ShippingMethodCode": "Express Courier (Air)", "Discounts": [], "Markups": [], "LoyaltyPointsSpent": null, "LoyaltyPointsEarned": null, "SameDayDispatch": false, "SameDayDispatchCost": 0.0, "DoNotChargeVAT": false, "CustomerComments": null, "IsFreeShipping": false, "FreeShippingCouponCode": null, "ShipToStoreCode": null, "RoundingRate": 0.0, "UrlParameters": "[{\"Key\":\"ClientCookie\",\"Value\":\"JSESSIONID=null\"},{\"Key\":\"userId\",\"Value\":\"1148993\"},{\"Key\":\"orderId\",\"Value\":\"w748807\"},{\"Key\":\"locale\",\"Value\":\"en_IL\"}]", "OriginalMerchantTotalProductsDiscountedPrice": 0.0, "LoyaltyCode": null, "OTVoucherCode": null, "OTVoucherAmount": null, "OTVoucherCurrencyCode": null, "IsSplitOrder": false, "PrePayOffered": false, "InitialCheckoutCultureCode": null, "CultureCode": null, "HubId": 0, "IsReplacementOrder": false, "OriginalOrder": null, "ReservationRequestId": null, "IsSuppressPersonalInformation": false, "TotalDutiesAndTaxesPrice": 0.0, "USSalesTax": 0.0, "CCFPrice": 0.0, "PaymentDetails": null, "PrimaryBilling": { "FirstName": null, "LastName": null, "MiddleName": null, "Salutation": null, "Company": null, "Address1": null, "Address2": null, "City": null, "StateCode": null, "StateOrProvince": null, "Zip": null, "Email": null, "Phone1": null, "Phone2": null, "Fax": null, "CountryCode": null, "CountryCode3": null, "CountryName": null, "AddressBookId": null, "AddressBookName": null, "SaveAddress": false }, "SecondaryBilling": { "FirstName": null, "LastName": null, "MiddleName": null, "Salutation": null, "Company": null, "Address1": null, "Address2": null, "City": null, "StateCode": null, "StateOrProvince": null, "Zip": null, "Email": null, "Phone1": null, "Phone2": null, "Fax": null, "CountryCode": null, "CountryCode3": null, "CountryName": null, "AddressBookId": null, "AddressBookName": null, "SaveAddress": false }, "OrderId": null, "StatusCode": null, "MerchantGUID": "7f132fc6-bdbc-420e-a2ce-fd35ab5c06d0", "CartId": "_2S0DVucAbjgfHAR-SUmRshWaS3pB5F9Bk7OfgWBR9ujllKrTw5H!17426857!1596453641116", "MerchantOrderId": null, "PriceCoefficientRate": 0.0, "CartHash": "94210A58BAC3B3AB292DE94382910C87", "WebStoreCode": "en_IL", "WebStoreInstanceCode": "GlobalEDefaultStoreInstance", "DiscountedShippingPrice": 0.0, "InternationalDetails": null, "GiftCards": null }
Responses
Example of generic error:
Error code 3 is expected. An appropriate error message is shown to the customer and a new clean cart is generated.
{ "AmendedProducts": [], "Error": "3", "StackTrace": " at CallSite.Target(Closure , CallSite , Object )\r\n at GlobalE.GEM.BL.GEMProviders.BaseProviders.BaseGEMProvider.ParseReservationInfo(Object reservationInfo) in C:\\jenkins\\workspace\\GEPI\\787e4b5b9a7709ca06b57fcfbeb2bdb2\\GlobalE.GEM.BL\\GEMProviders\\BaseProviders\\BaseGEMProvider.cs:line 844", "ReservationRequestId": null }
Example of invalid email error:
Error code 2 is expected. An appropriate error message is shown to the customer and a new clean cart is generated.
{ "AmendedProducts": [], "Error": "2", "StackTrace": null, "ReservationRequestId": null }
Example of invalid cart content error:
Error code 1 is expected. One of the cart fields is invalid. An appropriate error message is shown to the customer and a new clean cart is generated.
{ "AmendedProducts": [], "Error": "1", "StackTrace": null, "ReservationRequestId": null }
If all products are in stock:
{ "AmendedProducts": [], "ReservationRequestId": null, "Error": null }
If some products are out of stock:
{ "AmendedProducts": [{ "CartItemID": "11007", "QuantityInStock": 1 } ], "ReservationRequestId": null }
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 | Provides information related to validating a voucher in a cart. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
Merchant.VoucherValidationResponse | Provides information related to the voucher validation. |
Objects for ValidateVoucher API
Examples
Request
{ "CartHash": "", "CartId": "36048", "CartToken": "f8a78edd-7cea-4cb7-835c-57c7f0b13c56", "CountryCode": "IL", "CurrencyCode": "ILS", "Discounts": [], "FreeShippingCouponCode": "", "IsFreeShipping": false, "MerchantGUID": "e967e65e-f69e-479c-949d-91289a7f6875", "Products": [], "UserId": null, "VoucherCode": "10Perc", "VoucherType": 1, "WebStoreCode": null, "WebStoreInstanceCode": "GlobalEDefaultStoreInstance" }
Response
{ "IsVoucherValid": true, "VoucherType": 1, "CartToken": "f8a78edd-7cea-4cb7-835c-57c7f0b13c56", "VoucherValidationRestriction": [], "ValidationFaliureMessage": "" }