Skip to main content

Documentation Portal

Endpoints: Merchant APIs

Implement the four merchant endpoints detailed in the following sections. This Implementation is mandatory. We recommend exposing API methods via HTTPS.

Optionally, you can implement additional merchant APIs and APIs on the Global‑e Side.

Special Features and Requirements
  • If some of your products have reduced VAT rates (for example, you are a UK merchant with children's clothing), set the relevant reduced VAT rates for these products in the HTML data attribute. See Reduced VAT Rate Support.  

  • If you require support for product country exceptions (for example, restrict browsing before reaching the Global‑e checkout), set the relevant data-countries for these products in the HTML data attribute. See Product-specific VAT Rates in the EU and Restrictions.  

  • If you require the application of price coefficients to specific product classes (for example, on premium items in specific territories), set the relevant data-pc for these products in the HTML data attribute and the ProductClassCode in the GetCheckoutCartInfo (to Merchant) API.GetCheckoutCartInfo (to Merchant)

  • If you require support for existing logistics accounts, call a Global‑e API method to download the international commercial invoice for the specified order.

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.

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

countryCode

String

2-char ISO code for the country to which shipped

No

currencyCode

String

3-char currency code for the country to which shipped

No

merchantCartToken

String

Identifier used for the cart by the Merchant’s site

No

Response

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

CheckoutCartInfo

Object CheckoutCartInfo

Retrieves cart information

Examples
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 the Merchant.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 the SendAdditionalRequiredDocumentsToMerchant webhook.

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.

Examples
UpdateOrderStatus (Global-e to Merchant)

Updates the order status on the merchant's site. Only order.OrderId and order.StatusCode members are mandatory for this method.

This method is required to support order cancellation when 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

Requests can contain more parameters than listed.

Request

Name

Type

Description

Mandatory

order

Object Merchant.Order

Merchant.Order objects contain information about orders.

Yes

Response

Note

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

Name

Type

Description

ResponseInfo

Object Merchant.ResponseInfo

Indicates if the API call was successful or not and why.

Request Body
{
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "OrderId": "GE123874638GB",
    "MerchantOrderId": "14123332",
    "StatusCode": "canceled"
}
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.

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

Merchant.Order objects contain information about orders.

Yes

Examples