Authorize payment. Commit order.

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	Yes	Session ID must be passed in the header to authorize the user.
`Locally-Pl-Jwt` 🏷️	string	No	JSON Web Token passed in the header to identify the user. Does not expire.
`hash`	string	Yes	The cart hash.
`first_name`	string	Yes	First name of the customer.
`last_name`	string	Yes	Last name of the customer.
`full_name`	string	Yes	Full name of the customer.
`email`	string	Yes	Email address of the customer.
`phone`	string	No	Phone number with country code of the customer.
`address`	string	Yes	Address of the customer.
`city`	string	Yes	City of the customer.
`state`	string	No	State of the customer.
`zip`	integer	Yes	ZIP code of the customer.
`country`	string	Yes	Country code of the customer.
`is_opt_in_consent`	integer	Yes	Flag indicating customer's consent for marketing emails. 1 for true, 0 for false. One of: `0`, `1`.
`is_opt_in_consent_brand`	integer	Yes	Flag indicating customer's consent for brand marketing emails. 1 for true, 0 for false. One of: `0`, `1`.
`setup_intent_id`	string	Yes	Stripe setup intent ID.

Example Request

curl 'https://www.locally.com/headless/api/1.0/cart/order' \
--request POST \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Api-Session-Id: {{SESSION_ID}}' \
--url-query 'hash={{CART_HASH}}' \
--url-query 'first_name=Jane' \
--url-query 'last_name=Doe' \
--url-query 'full_name=Jane Doe' \
--url-query '[email protected]' \
--url-query 'phone=+15555555555' \
--url-query 'address=123 W Madison St' \
--url-query 'city=Chicago' \
--url-query 'state=IL' \
--url-query 'zip=60602' \
--url-query 'country=US' \
--url-query 'is_opt_in_consent=1' \
--url-query 'is_opt_in_consent_brand=1' \
--url-query 'setup_intent_id={{SETUP_INTENT_ID}}'

const params = new URLSearchParams({
  hash: '{{CART_HASH}}',
  first_name: 'Jane',
  last_name: 'Doe',
  full_name: 'Jane Doe',
  email: '[email protected]',
  phone: '+15555555555',
  address: '123 W Madison St',
  city: 'Chicago',
  state: 'IL',
  zip: '60602',
  country: 'US',
  is_opt_in_consent: '1',
  is_opt_in_consent_brand: '1',
  setup_intent_id: '{{SETUP_INTENT_ID}}'
});

const response = await fetch(`https://www.locally.com/headless/api/1.0/cart/order?${params}`, {
  method: 'POST',
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}',
    'Locally-Api-Session-Id': '{{SESSION_ID}}'
  }
});
const data = await response.json();

import requests

params = {
    "hash": "{{CART_HASH}}",
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15555555555",
    "address": "123 W Madison St",
    "city": "Chicago",
    "state": "IL",
    "zip": 60602,
    "country": "US",
    "is_opt_in_consent": 1,
    "is_opt_in_consent_brand": 1,
    "setup_intent_id": "{{SETUP_INTENT_ID}}",
}

response = requests.post(
    "https://www.locally.com/headless/api/1.0/cart/order",
    params=params,
    headers={
        "Locally-Api-Token": "{{API_TOKEN}}",
        "Locally-Api-Session-Id": "{{SESSION_ID}}",
    },
)
data = response.json()

The cart identified by hash must already be associated with the shopper's session (Locally-Api-Session-Id) or with a cart JWT passed in the optional Locally-Pl-Jwt header. setup_intent_id is a Stripe setup intent ID — see Creating a BOPIS order for how it is constructed.

Example Response

{
  "success": true,
  "data": {
    "message": "Your order has been placed",
    "target_uri": "/order/QE3QL6/U8KM2P",
    "status_code": 200,
    "session": {
      "id": "vD2kq9mXw4bT7nR5cJ1sL8fA3gH6pZ0yE2uN4iK9"
    }
  },
  "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.message — Shopper-facing order outcome (here Your order has been placed). Placing an order does not capture funds — in most cases Locally captures only after the store confirms stock.
data.target_uri — Relative URI of the shopper's order status page on locally.com, built from the cart hash and a buyer-only secret. Send the shopper here to track the order.
data.status_code — HTTP-style result of order processing duplicated inside the payload; 200 means the order was placed. Failures surface as a non-200 HTTP response with an error envelope instead.
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.