Orders

Posting orders here is what gets you the WhatsApp order lifecycle: each status change messages the customer with the right update, using the workspace's own templates, without you writing any of it.

Paths are relative to https://api.chatboxai.dev/api, so /v1/messages/template means https://api.chatboxai.dev/api/v1/messages/template. Every request needs an API key, see Authentication.

List orders

GET/v1/orders
Scopeorders:readPaginated
Query parameterNotes
pageFrom 1.
pageSizeDefault 25, maximum 100.
statusOnly orders in this status.
contactIdOnly this contact's orders.

Get an order

GET/v1/orders/{id}
Scopeorders:read

Returns one order, in the same shape as the create response below.

Create an order

POST/v1/orders
Scopeorders:writeIdempotent
Request
POST /api/v1/orders
Idempotency-Key: shopify-order-1234

{
  "to": "+919999900000",
  "name": "Asha Menon",
  "currency": "INR",
  "notes": "14 MG Road, Kochi 682016. Leave with security.",
  "items": [
    { "productId": "SKU-221", "title": "Filter coffee 500g", "qty": 2, "price": 420 },
    { "title": "Steel tumbler", "qty": 1, "price": 659 }
  ]
}
Response
{
  "id": "clx9q7r4v0005",
  "contactId": "clx8h2k9p0001",
  "status": "PENDING",
  "total": "1499.00",
  "currency": "INR",
  "items": [ ... ],
  "notes": "14 MG Road, Kochi 682016. Leave with security.",
  "paymentLink": null,
  "createdAt": "2026-10-17T10:20:00.000Z",
  "updatedAt": "2026-10-17T10:20:00.000Z"
}

total is computed from the items and returned as a decimal string, so it survives a round-trip through JavaScript without losing paise.

Change an order's status

PATCH/v1/orders/{id}/status
Scopeorders:write
Request body
{ "status": "SHIPPED" }

Valid statuses: CART, PENDING, SHIPPED, DELIVERED, CANCELLED, ABANDONED. A move that makes no sense (CANCELLED after DELIVERED) is refused, because each move messages the customer and a nonsensical move is a nonsensical message.

PAID is refused

An order is marked paid by the payment itself. Take the money through your own checkout and post the order as PENDING, or use a Chatbox payment link so the payment webhook moves it. If we let an API call mark an order paid, a bug in a plugin would tell a customer their money had arrived when it had not.