> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stage.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipping Options Details

> Retrieve estimated shipping rates and free-shipping thresholds for a destination — the cheapest rate per cart/product (GetShippingDetails) or all flat-rate thresholds for all services (GetShippingDetailsExtended).

## 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

<div className="api-ref-card">
  <Card title="Get shipping details — reference & playground" icon="truck" href="/api-reference/get-shipping-details">
    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`.
  </Card>
</div>

<div className="api-ref-card">
  <Card title="Get shipping details extended — reference & playground" icon="layer-group" href="/api-reference/get-shipping-details-extended">
    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`.
  </Card>
</div>

## 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`).

```json Request theme={null}
{
    "destinationCountry": "USA",
    "amount": 50,
    "currencyCode": "USD",
    "productCodes": []
}
```

```json Response theme={null}
[
    {
        "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`).

```json Request theme={null}
{
    "amount": 100,
    "currencyCode": "USD",
    "productCodes": null,
    "cultureCode": "es"
}
```

```json Response theme={null}
[
    {
        "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
            }
        ]
    }
]
```

<Note>
  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.
</Note>

## 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.                                                   |