Set Chosen Delivery Option

Request Parameters

🏷️ header · 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	No	Session ID must be passed in the header to authorize the user, if not passing `Locally-Pl-Jwt`.
`Locally-Pl-Jwt` 🏷️	string	No	JSON Web Token passed in the header to identify the user, if not passing `Locally-Api-Session-Id`. Does not expire.
`hash`	string	Yes	The hash of the cart.
`delivery_estimate_id`	string	Yes	The delivery estimate ID to select.

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart/delivery/options/chosen' \
--request PUT \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Pl-Jwt: {{JWT}}' \
--url-query 'hash={{CART_HASH}}' \
--url-query 'delivery_estimate_id=928101'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/cart/delivery/options/chosen?hash={{CART_HASH}}&delivery_estimate_id=928101',
  {
    method: 'PUT',
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}',
      'Locally-Pl-Jwt': '{{JWT}}'
    }
  }
);
const data = await response.json();

import requests

response = requests.put(
    'https://www.locally.com/headless/api/1.0/cart/delivery/options/chosen',
    params={
        'hash': '{{CART_HASH}}',
        'delivery_estimate_id': '928101'
    },
    headers={'Locally-Api-Token': '{{API_TOKEN}}', 'Locally-Pl-Jwt': '{{JWT}}'}
)
data = response.json()

delivery_estimate_id is the id of one of the delivery estimates previously returned for this cart (see the Get delivery options endpoint). The chosen option can be changed with repeat calls until the order is placed; once the cart is ordered, this endpoint returns a 400 error.

The caller must be identified as the cart's owner, either by an already-authenticated session (Locally-Api-Session-Id) or by a Locally-Pl-Jwt naming this exact cart — the hash alone is not sufficient proof of ownership. Read more about where to get a cart's session ID and JWT.

Example Response

{
  "success": true,
  "data": {
    "id": 999,
    "user_id": 999,
    "hash": "QE3QL6",
    "is_ordered": 0,
    "origin": "www.example.com",
    "locale": "en-us",
    "cart_currency": "USD",
    "first_name": "TEST",
    "last_name": "USER",
    "address": "2020 W Willow St",
    "address_2": "",
    "city": "Chicago",
    "state": "IL",
    "zip": "60647",
    "country": "US",
    "email": "[email protected]",
    "phone": "+10000000000",
    "for_hold": 0,
    "for_ship_to_store": 0,
    "for_delivery": 1,
    "delivery_choice": "928101",
    "delivery_first_name": "TEST",
    "delivery_last_name": "USER",
    "delivery_address": "2020 W Willow St",
    "delivery_address_2": "",
    "delivery_city": "Chicago",
    "delivery_state": "IL",
    "delivery_zip": "60647",
    "delivery_country": "US",
    "delivery_notes": "",
    "delivery_status": "",
    "store_delivery_fee": 0,
    "delivery_fee_total": 7.99,
    "subtotal": 100,
    "tax_total": 10.10,
    "shipping_cost_total": 0,
    "coupon_code": "",
    "coupon_discount_total": 0,
    "grand_total": 118.09,
    "is_buyable": 1,
    "is_deliverable": 1,
    "created_at": "2026-07-16 14:03:11",
    "updated_at": "2026-07-16 14:09:45",
    "items": [
      {
        "id": 999,
        "cart_id": 999,
        "qty": 1,
        "upc": "000000000000",
        "product_name": "ACME Outfitters Widget",
        "product_company_name": "ACME Outfitters",
        "product_image": "image.jpg",
        "product_color": "Red",
        "product_size": "M",
        "product_price": 100,
        "product_id": 999999,
        "product_company_id": 999,
        "product_currency": "USD",
        "store_id": 99999,
        "qty_available": 10,
        "message": "",
        "fulfillment_type": 0,
        "subtotal": 100,
        "tax_total": 10.10,
        "shipping_cost": 0,
        "coupon_discount_total": 0,
        "vat": 0,
        "grand_total": 110.10
      }
    ],
    "delivery": null,
    "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.hash — Unique short identifier for the cart. Other endpoints accept it as the hash parameter, and it appears in order URIs.
data.is_ordered — 0 until the order is placed. Once it flips to 1 the delivery option is locked, and further calls to this endpoint return HTTP 400.
data.for_delivery — Fulfillment-mode flag alongside for_hold and for_ship_to_store. This call forces it to 1, marking the cart as a delivery order.
data.delivery_choice — The delivery_estimate_id you selected, echoed back as a string. Locally keeps it in sync with the delivery record's chosen_estimate_id once that record exists.
data.delivery_status — Numeric delivery-progress stage: 0/empty until the order is placed, later advancing through 60 (pickup), 70 (pickup_complete), and 90 (delivered); 50 means canceled.
data.delivery_fee_total — Customer delivery fee in dollars for the chosen estimate, folded into grand_total together with subtotal, tax, any courier tip, and coupon discounts.
data.delivery — null until the order is placed — Locally creates the delivery record (carrier, locked-in fees, tracking) at order time. The Set Delivery Option Used endpoint requires that record.
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.