Manual delivery status update

Request Parameters

🏷️ header · unmarked parameters are query params

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart/update/delivery/status' \
--request POST \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Pl-Jwt: {{JWT}}' \
--url-query 'hash={{CART_HASH}}' \
--url-query 'status=2'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/cart/update/delivery/status?hash={{CART_HASH}}&status=2',
  {
    method: 'POST',
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}',
      'Locally-Pl-Jwt': '{{JWT}}'
    }
  }
);
const data = await response.json();
console.log(data);

import requests

url = "https://www.locally.com/headless/api/1.0/cart/update/delivery/status"
headers = {"Locally-Api-Token": "{{API_TOKEN}}", "Locally-Pl-Jwt": "{{JWT}}"}
params = {"hash": "{{CART_HASH}}", "status": "2"}

response = requests.post(url, headers=headers, params=params)
print(response.json())

status is a numeric delivery stage: 1 (canceled), 2 (pickup), 3 (pickup_complete), 4 (dropoff), or 5 (delivered). The cart referenced by hash must be a test cart placed as a delivery order.

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": {
        "delivery_status": 60,
        "mock_status": "2 - pickup",
        "session": {
            "id": "abc999"
        }
    },
    "msg": "Delivery status updated to 2."
}

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_status — The cart's delivery stage after the update: 50 canceled, 60 pickup, 70 pickup_complete/dropoff, 90 delivered — not the 1–5 request codes. Each stage advance also fires the matching delivery webhook.
• data.mock_status — Echo of the requested stage as code - name: 1 canceled, 2 pickup, 3 pickup_complete, 4 dropoff, 5 delivered.
• 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 status text. Unlike most endpoints it is populated on success (Delivery status updated to 2.); on failure it carries the error text alongside a top-level error_code.