Get delivery options

Request Parameters

🏷️ header · 📦 body field · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`Locally-Api-Session-Id` 🏷️	string	Yes	Session ID must be passed in the header to persist the user session. Can expire.
`is_possible_conventional` 📦	boolean	Yes	Whether to include conventional delivery options.
`is_possible_sdd` 📦	boolean	Yes	Whether to include same-day delivery options.
`delivery_quote_uuid` 📦	string	No	Optional UUID of an existing delivery quote.
`detail_level` 📦	string	No	Level of detail to return. One of: `simple`, `full`.
`cart_data.store_id` 📦	integer	Yes
`cart_data.items[].upc` 📦	string	No
`cart_data.items[].qty` 📦	integer	No
`cart_data.items[].price_per_unit` 📦	integer	No
`customer_data.first_name` 📦	string	No
`customer_data.last_name` 📦	string	No
`customer_data.address_1` 📦	string	Yes
`customer_data.address_2` 📦	string	No
`customer_data.city` 📦	string	Yes
`customer_data.state` 📦	string	Yes
`customer_data.zip` 📦	string	Yes

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart/get-delivery-options' \
--request POST \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Api-Session-Id: {{SESSION_ID}}' \
--header 'Content-Type: application/json' \
--data '{
  "is_possible_conventional": true,
  "is_possible_sdd": true,
  "detail_level": "simple",
  "cart_data": {
    "store_id": 37175,
    "items": [
      {
        "upc": "686487455948",
        "qty": 1
      }
    ]
  },
  "customer_data": {
    "first_name": "TEST",
    "last_name": "USER",
    "address_1": "2020 W Willow St",
    "address_2": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60647"
  }
}'

const response = await fetch('https://www.locally.com/headless/api/1.0/cart/get-delivery-options', {
  method: 'POST',
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}',
    'Locally-Api-Session-Id': '{{SESSION_ID}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    is_possible_conventional: true,
    is_possible_sdd: true,
    detail_level: 'simple',
    cart_data: {
      store_id: 37175,
      items: [{ upc: '686487455948', qty: 1 }]
    },
    customer_data: {
      first_name: 'TEST',
      last_name: 'USER',
      address_1: '2020 W Willow St',
      address_2: '',
      city: 'Chicago',
      state: 'IL',
      zip: '60647'
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://www.locally.com/headless/api/1.0/cart/get-delivery-options',
    headers={
        'Locally-Api-Token': '{{API_TOKEN}}',
        'Locally-Api-Session-Id': '{{SESSION_ID}}'
    },
    json={
        'is_possible_conventional': True,
        'is_possible_sdd': True,
        'detail_level': 'simple',
        'cart_data': {
            'store_id': 37175,
            'items': [{'upc': '686487455948', 'qty': 1}]
        },
        'customer_data': {
            'first_name': 'TEST',
            'last_name': 'USER',
            'address_1': '2020 W Willow St',
            'address_2': '',
            'city': 'Chicago',
            'state': 'IL',
            'zip': '60647'
        }
    }
)

data = response.json()

With detail_level set to simple, the response returns only the cheapest option in each category; full lists every available carrier. Pass the delivery_quote_uuid from a previous response to reuse an existing quote instead of generating a new one.

Example Response

{
    "success": true,
    "data": {
        "delivery_quote_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "conventional_delivery": {
            "store_id": 37175,
            "items": [
                {
                    "upc": "686487455948",
                    "qty": 1
                }
            ],
            "delivery_options": {
                "standard": {
                    "delivery_estimate_id": 928101,
                    "fee": 9.99,
                    "carrier_name": "USPS"
                },
                "2_day": {
                    "delivery_estimate_id": 928102,
                    "fee": 18.5,
                    "carrier_name": "USPS"
                },
                "next_day": {
                    "delivery_estimate_id": 928103,
                    "fee": 32.75,
                    "carrier_name": "UPS"
                }
            }
        },
        "same_day_delivery": {
            "store_id": 37175,
            "local_delivery_window": "Today",
            "items": [
                {
                    "upc": "686487455948",
                    "qty": 1
                }
            ],
            "fee": 12.99,
            "delivery_estimate_id": 928104,
            "carrier_name": "Roadie"
        },
        "session": {
            "id": "4f6d0e2b8c1a9e3d5b7f0a2c4e6d8b1a3c5e7f90"
        }
    },
    "msg": ""
}

Response Explanation

success — Boolean outcome of the call. When false, the response also carries a top-level error_code and explanatory msg — always check success, not just the HTTP status.
data.delivery_quote_uuid — Identifier of the delivery quote grouping these estimates. Pass it back as delivery_quote_uuid to price against the same quote; repeat store-plus-address requests within an hour reuse it automatically.
data.conventional_delivery — Parcel-shipping options. null when is_possible_conventional is false or no parcel carrier returned a usable estimate.
data.conventional_delivery.delivery_options — Grouped by speed class: standard, 2_day, next_day. With detail_level: simple each class holds only its cheapest option; with full each holds a carriers array listing every quote.
data.conventional_delivery.delivery_options.standard.delivery_estimate_id — Identifier of this priced estimate (present on every option, including same-day) — pass it as delivery_estimate_id when setting the chosen or used delivery option. Estimates expire within minutes.
data.same_day_delivery — Local courier option. null when is_possible_sdd is false or no courier quoted. simple returns only the cheapest courier, flattened onto this object; full returns a carriers array instead.
data.same_day_delivery.local_delivery_window — Earliest local dropoff day — Today, Tomorrow, or a date like Jan 29 — computed from store hours and the store's dispatch cutoff (default four hours before close).
data.same_day_delivery.fee — Fee charged to the customer, in dollars (never cents). May be a store-configured flat rate rather than the carrier's raw rate. Applies to every fee in this response.
data.session.id — Locally session ID, returned on every response. Replay it via the Locally-Api-Session-Id header to persist the shopper's session between calls; expired IDs are transparently replaced with fresh ones.
msg — Human-readable error text; empty string on success. In production, unexpected server errors are masked as App server error with a lookup reference — see Handling Errors in Production.