Shipping Options Details

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

Make sure you have 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).

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.

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.

GetShippingDetails API Structure

Retrieves shipping details per cart or mini cart and product page.

Endpoint URL

POST {base_URL_GE}/ShippingDetails/GetShippingDetails

Request Parameters

Parameter name	Data type	Mandatory	Comment
merchantGUID	String	No, if used for the JWT implementation (since it has been used in the Authorization and UserName headers)	Unique Merchant Identifier and API token. The Merchant Identifier is different for test and live environments. If not used, make sure to implement the JWT authentication.JWT Authentication_For GE API TBD

Parameter name

Data type

Mandatory

Comment

merchantGUID

String

No, if used for the JWT implementation (since it has been used in the Authorization and UserName headers)

Unique Merchant Identifier and API token.

The Merchant Identifier is different for test and live environments.

If not used, make sure to implement the JWT authentication.JWT Authentication_For GE API TBD

Request Body

Parameter name	Data type	Mandatory	Description
`destinationCountry`	String	No	The destination country Length: 2-3 letters (both ISO-2 and ISO-3 are supported) If empty, the API returns a list of shipping rates for all countries configured in the Global-e System. Example: US or USA for the United States
`currencyCode`	String	Yes	The country's currency code. Length: 3 letters Example: CAD , USD , ILS , EUR
`amount`	Decimal (Float)	Yes	The shipping cost This number can contain up to two digits after the decimal point Example: 50.30
`productCodes`	Array	No	The unique product reference (SKU, EAN, Barcode, and more.) `["product123","productABC"]`

Request Response

The API response can include up to two objects per destination:

Object with the cheapest estimated shipping cost for the submitted currency and amount value
Object with the Free Shipping threshold range (where applicable).

The returned data is determined by the submitted amount, that is, 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.

Parameters

Parameter name	Data Type	Description
`destinationCountry`	String	The destination country's ISO code Length: 2/3-letters ISO country code based on the request value Example: ISR, IL, USA, US
`status`	String	Shipping methods availability `Active`: Shipping methods were found for this destination `noShippingMethodsAvailable`: No active shipping methods were found. Shipments to the selected destination are currently not supported.
`shippingRates`	Array	This array contains up to two shipping service objects. These two shipping rate objects that can be returned are as per the Shipping Details API logic. For more information, see Shipping Details. If the cheapest shipping service is the first to be subject to free shipping, only one shippingRates object is returned. Example: [ { "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": 5.0000, "shippingCostCurrency": "USD", "shippingPriority": "Express Courier (Air)", "estimatedDeliveryDays": "1-3", "specialOfferExpiryDate": null } ] } ]
`minOrderSubtotal`	Decimal	Minimum order/product price for a price range (includes 4 decimals) Example: 100.0000
`maxOrderSubtotal`	Decimal	Maximum order/product price for a price range (includes 4 decimals) Example: 15.000
`shippingCost`	Decimal	The shipping costs for the order/product price range (includes 4 decimals) Example: 5.0000
`shippingCostCurrency`	String	The merchant's default currency for the destination (3 letters ISO code) Example: EUR, USD, ILS
`shippingPriority`	String	The type of shipping service Shipping types: standard, express, tracked, and more. Example: Standard, Express Courier (Air)
`estimatedDeliveryDays`	String	The estimated number of days required for the selected shipping service to deliver to the selected destination country. This parameter displays the widest range for the aggregated shipping methods available for the submitted values on the pre-checkout page. Example: 1-3 days. Two shipping methods are available for the submitted values, one ranging between 1-3 delivery days and the other 4-5 delivery days. Thus, the estimated output range is 1-3 days. Note: This parameter does NOT include the additional days configured in the Global-e system for fulfillment.
`specialOfferExpiryDate`	String	The expiration date and time for the special offer `DATE/TIME` Displayed when the returned shipping object is linked to an active marketing campaign configured in the Global-e system. Date/time format: `yyyy-mm-ddThh:mm:ss` Example: `2022-11-30T00:00:00` `NULL` Displayed for campaigns/ rates without expiration dates and times.

Sample

Body (Example):

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

Response (Example):

[
    {
        "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
            }
        ]
    }
]

FAILED RESPONSES

ERROR CODE: 500

JWT authentication issue (for example, wrong credentials or expired token).

{
  "Code": "500",      
  "Error": "Error occurred, Please contact Global‑e",    
  "Description": "Please send valid authentication token/userName in HTTP headers (Authorization/UserName)"    
}

ERROR CODE 401

The authorization has failed for this merchant GUID.

Note: The merchantGUID is different for test and live environments.

{
    "Code": "401",
    "Error": "Parameter merchantGUID is not a valid GUID. Provided value C064DA15-65E6-42B7-B705-3554FC631.
    MerchantId=",
    "Description": "Please provide the valid merchantGUID as supplied to you during initial setup"
}

ERROR CODE 400

Issues with the data passed in the request payload.

{
    "Code": "400",
    "Error": "Invalid country code",
    "Description": "Country with code UT not found"
}

{
    "Code": "400",
    "Error": "Parameter Amount was not a number", 
    "Description": "Please provide a valid value for the Amount parameter"
}

{
    "Code": "400",
    "Error": "Invalid currency code",
    "Description": "Currency with code D not found"
}

MISSING PARAMETER ERROR

{
    "Code": "EmptyString",
    "Error": "Parameter Currency was empty or null",    
    "Description": "Please provide a valid value for the Currency parameter"
}

GetShippingDetailsExtended

This API extends the GetShippingDetails API to provide all flat shipping rate thresholds for all shipping services related to a product.

The GetShippingDetailsExtended API lets you:

Get all shipping rates available for a given country
Get the rates for all specific shipping service levels
Revert to all shipping rates available, for instance, if the request passed with amount = 0.

Endpoint: {base_URL_GE}/ShippingDetails/GetShippingDetailsExtended

Parameters

Parameter	Type	Description	Mandatory	Default Values
`DestinationCountry`	String	The destination country Length: 2-3 letters (both ISO-2 and ISO-3 are supported) If empty, the API returns a list of shipping rates for all countries configured in the Global-e System. Example: US or USA for the United States	Yes
`Amount`	Decimal (Float)	The shipping cost This number can contain up to two digits after the decimal point Example: 50.30	Yes
`CurrencyCode`	String	The country's currency code. Length: 3 letters Example: CAD , USD , ILS , EUR	Yes
`ProductCodes`	Array	The unique product reference (SKU, EAN, Barcode, and more.) `["product123","productABC"]`	No
`ServiceLevel`	Integer	Supported Service levels (default) = Revert to all shipping rates available, for instance, if the request passed with amount = 0. `Standard = 1,` `Express = 2,` `PriorityPost = 3,` `Airmail = 4,` `VirtualGoods = 5,` `ExpressCourierWithoutSameDay = 6,` `UntrackedPost = 7,` `StoreCollection = 8,` `StandardPost = 9,` `StandardCourier = 10,` `ExpressShipping = 11,` `StandardShipping = 12,` `CollectionPoint = 13,` `MerchantOwnCarriage = 14,` `TrackedStandard = 15,` `ExpressPlus = 16,` `StandardExpress = 17,` `PremiumStandard = 18,` `TrackedPostToPickupLocation = 19`	No	Default output for all service levels (express / standard / ...
`CultureCode`	String	Determines the shipping method description language.	No	en-GB

Example of a request to return all services to all countries with a localized name in Spanish:

{
    "Amount": "100",
    "CurrencyCode": "USD",
    "ProductCodes": null,
    "CultureCode": "es"
}

Response: All the available rates (by flat rates shipping campaign).

{
    "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
        }, {
            "shippingMethodLocalizedName": "Envío express",
            "shippingMethodName": "Express Courier (Air)",
            "rangeMinValue": 440.0000,
            "rangeMaxValue": 999999999.0000,
            "shippingCost": 0.0000,
            "shippingCostCurrency": "EUR",
            "estimatedDeliveryDays ": "1-2",
            "specialOfferExpiryDate ": null
        }, {
            "shippingMethodLocalizedName": "Envío estándar",
            "shippingMethodName": "Standard Courier",
            "rangeMinValue": 440.0000,
            "rangeMaxValue": 999999999.0000,
            "shippingCost": 0.0000,
            "shippingCostCurrency": "EUR",
            "estimatedDeliveryDays ": "2-10",
            "specialOfferExpiryDate ": null
        }
    ]
}, {
    "destinationCountry": "GB",
    "status": "active",
    "shippingRates": [{
            "shippingMethodLocalizedName": "Envío express",
            "shippingMethodName": "Express Courier (Air)",
            "rangeMinValue": 0.0000,
            "rangeMaxValue": 10000000000.0000,
            "shippingCost": 10.0000,
            "shippingCostCurrency": "USD",
            "estimatedDeliveryDays ": "1-1",
            "specialOfferExpiryDate ": null
        }, {
            "shippingMethodLocalizedName": "Envío estándar",
            "shippingMethodName": "Standard Courier",
            "rangeMinValue": 0.0000,
            "rangeMaxValue": 10000000000.0000,
            "shippingCost": 10.0000,
            "shippingCostCurrency": "USD",
            "estimatedDeliveryDays ": "2-2",
            "specialOfferExpiryDate ": null
        }
    ]
},

Parameters

Parameter	Type	Description
`shippingMethodLocalizedName`	String	The name of the shipping method type name
`shippingMethodName`	String	The type of shipping service Shipping types: standard, express, tracked, and more. Example: Standard, Express Courier (Air)
`rangeMinValue`	Decimal	Double representation of range minimum value Minimum order/product price for a price range (includes 4 decimals) Example: 100.0000
`rangeMaxValue`	Decimal	Double representation of range minimum value Maximum order/product price for a price range (includes 4 decimals) Example: 150.0000
`shippingCost`	Decimal	The shipping costs for the order/product price range (includes 4 decimals) Example: 5.0000
`shippingCostCurrency`	String	The merchant's default currency for the destination (3 letters ISO code) Example: EUR, USD, ILS
shippingRates	Array	This array contains up to two shipping service objects. These two shipping rate objects that can be returned are as per the Shipping Details API logic. For more information, see Shipping Details. If the cheapest shipping service is the first to be subject to free shipping, only one shippingRates object is returned. Example: [ { "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": 5.0000, "shippingCostCurrency": "USD", "shippingPriority": "Express Courier (Air)", "estimatedDeliveryDays": "1-3", "specialOfferExpiryDate": null } ] } ]

Documentation Portal

Shipping Options Details

Prerequisites

API Access

Permissions and Credentials

GetShippingDetails API Structure

Sample

GetShippingDetailsExtended