Shipping Options Details

Overview

The Shipping Options Details APIs retrieve estimated shipping rates for a destination, which you can present on the pre-checkout page, product page, or cart.

GetShippingDetails — Retrieves shipping details per cart or mini cart and product page. Returns up to two shipping-rate objects per destination: the cheapest estimated shipping cost for the submitted currency and amount, and the Free Shipping threshold range (where applicable).
GetShippingDetailsExtended — Extends GetShippingDetails to provide all flat shipping-rate thresholds for all shipping services related to a product. Use it to get all shipping rates available for a given country, get the rates for specific shipping service levels, or revert to all shipping rates available (for instance, when the request is passed with amount = 0).

Prerequisites

API Access

Global‑e must enable and configure each API on the Global‑e side. Make sure that Global‑e has enabled this API.

Permissions and Credentials

The API UserName header and the Authorization header, including the token retrieved via the GetAuthenticationToken API using merchant-specific credentials (provided to you by Global‑e). See the Authentication section under Global-e Environments.
Your merchantGUID. The merchantGUID is provided to you by Global‑e during the initial setup. Note that the merchantGUID is different for test and live environments.

Reference

Get shipping details — reference & playground

Request (destinationCountry, currencyCode, amount, productCodes), the per-destination response with the cheapest rate and free-shipping threshold, error shapes, examples, and the interactive playground for POST /ShippingDetails/GetShippingDetails.

Get shipping details extended — reference & playground

Request (amount, currencyCode, destinationCountry, productCodes, cultureCode, serviceLevel), the per-country response with all flat-rate thresholds for all services, examples, and the interactive playground for POST /ShippingDetails/GetShippingDetailsExtended.

Use Cases

1. Get the cheapest rate and free-shipping threshold

Call GetShippingDetails with the destination, currency, and amount. The response can include up to two objects per destination: an object with the cheapest estimated shipping cost for the submitted currency and amount, and an object with the Free Shipping threshold range (where applicable). The returned data is determined by the submitted amount — the response only returns a shipping service for which the amount passed in the request is greater than or equal to the minimum flat shipping rate range, and lower than the maximum flat shipping rate range (minimum flat shipping rate range ≤ product/cart amount < maximum flat shipping rate range).

Request

{
    "destinationCountry": "USA",
    "amount": 50,
    "currencyCode": "USD",
    "productCodes": []
}

Response

[
    {
        "destinationCountry": "USA",
        "status": "active",
        "shippingRates": [
            {
                "minOrderSubtotal": 0.0000,
                "maxOrderSubtotal": 100.0000,
                "shippingCost": 15.0000,
                "shippingCostCurrency": "USD",
                "shippingPriority": "Express Courier (Air)",
                "estimatedDeliveryDays": "1-3",
                "specialOfferExpiryDate": null
            },
            {
                "minOrderSubtotal": 100.0000,
                "maxOrderSubtotal": 9999999.0000,
                "shippingCost": 0.0000,
                "shippingCostCurrency": "USD",
                "shippingPriority": "Express Courier (Air)",
                "estimatedDeliveryDays": "1-3",
                "specialOfferExpiryDate": null
            }
        ]
    }
]

2. Get all rates for all services

Call GetShippingDetailsExtended to return all available shipping rates by flat-rate shipping campaign. The example below returns all services for all countries with a localized name in Spanish (cultureCode = es).

Request

{
    "amount": 100,
    "currencyCode": "USD",
    "productCodes": null,
    "cultureCode": "es"
}

Response

[
    {
        "destinationCountry": "FO",
        "status": "active",
        "shippingRates": [
            {
                "shippingMethodLocalizedName": "Envío express",
                "shippingMethodName": "Express Courier (Air)",
                "rangeMinValue": 0.0000,
                "rangeMaxValue": 10000000000.0000,
                "shippingCost": 35.0000,
                "shippingCostCurrency": "USD",
                "estimatedDeliveryDays": "3-10",
                "specialOfferExpiryDate": null
            }
        ]
    },
    {
        "destinationCountry": "FR",
        "status": "active",
        "shippingRates": [
            {
                "shippingMethodLocalizedName": "Envío estándar",
                "shippingMethodName": "Standard Courier",
                "rangeMinValue": 40.0000,
                "rangeMaxValue": 440.0000,
                "shippingCost": 0.0000,
                "shippingCostCurrency": "EUR",
                "estimatedDeliveryDays": "2-10",
                "specialOfferExpiryDate": null
            },
            {
                "shippingMethodLocalizedName": "Envío express",
                "shippingMethodName": "Express Courier (Air)",
                "rangeMinValue": 40.0000,
                "rangeMaxValue": 440.0000,
                "shippingCost": 15.0000,
                "shippingCostCurrency": "EUR",
                "estimatedDeliveryDays": "1-2",
                "specialOfferExpiryDate": null
            }
        ]
    }
]

The response is a JSON array of per-country objects, ordered by destination country. Additional countries in the source example (e.g. GB) are omitted here for brevity.

Error Codes

When calling GetShippingDetails, the following error codes may be returned.

Code	Description
`400`	Error. Problem with the data passed in the request payload.
`401`	Error. The authorization has failed for this merchant GUID. Note: the merchantGUID is different for test and live environments.
`500`	Issue with JWT authentication, such as wrong credentials or an expired token.

​Overview

​Prerequisites

​API Access

​Permissions and Credentials

​Reference

Get shipping details — reference & playground

Get shipping details extended — reference & playground

​Use Cases

​1. Get the cheapest rate and free-shipping threshold

​2. Get all rates for all services

​Error Codes

Overview

Prerequisites

API Access

Permissions and Credentials

Reference

Use Cases

1. Get the cheapest rate and free-shipping threshold

2. Get all rates for all services

Error Codes