Online orders

Online orders are orders that arrive from somewhere other than the till: your web shop, your app, an aggregator, a kiosk. Creating one puts it in front of the store exactly as a first-party order would be, including the realtime notification that makes the POS chime.

A Full API token includes the online-order scopes. If ordering is all your integration does, use the Online Order API instead — it is the same endpoints with a narrower bundle and no app review gate.

Endpoints

Method	Path	Scope
GET	/v1/online-orders	online_orders.read
GET	/v1/online-orders/:id	online_orders.read
GET	/v1/online-orders/:id/status	online_orders.read
POST	/v1/online-orders	online_orders.write

Create an order

curl -s "$API_BASE_URL/online-orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "storeId": 1,
    "orderType": 3,
    "status": 1,
    "customerId": 5521,
    "customerName": "Priya Nair",
    "customerPhone": "+919845012345",
    "note": "Leave at reception",
    "takenBy": "acme-web",
    "subtotal": 11.25,
    "taxAmount": 0.56,
    "totalAmount": 11.81,
    "items": [
      {
        "id": 8841,
        "item": "Flat White",
        "qty": 2,
        "rate": 3.75,
        "note": "extra hot",
        "itemModifiers": [14],
        "modifiers": [{ "ID": 41, "ModifierId": 14 }]
      },
      { "id": 8905, "item": "Almond croissant", "qty": 1, "rate": 3.75 }
    ]
  }'

Header fields

Field	Type	Required	Notes
storeId	number	yes	Which store fulfils the order
items	array	yes	At least one line
orderType	number	no	2 takeout, 3 delivery
status	number	no	0 draft, 1 new and visible to the store (default)
customerId	number	no	Existing customer. Create or match them first
customerName, customerPhone	string	no	Shown to the store when there is no customer record
subtotal, taxAmount, cessAmount, totalAmount	number	no	Your computed totals
tipAmount, tipPercent	number	no	Tip captured at checkout
note	string	no	Kitchen or delivery note
takenBy	string	no	Channel identifier — set it to your integration’s name

Line fields

Field	Type	Required	Notes
id	number	yes	The LithosPOS item id
item	string	yes	Item name as shown to the customer
qty	number	yes	Minimum 0
rate	number	yes	Unit price charged, minimum 0
variantId	number	no	0 when the item has no variants
note	string	no	Per-line preparation note
itemModifiers	number[]	no	Modifier group ids applied to the line
modifiers	{ ID, ModifierId }[]	no	Chosen options: ID is the option, ModifierId its group

Send prices you actually charged

The order carries your prices, not the catalogue’s. Reconcile against the merchant’s item rate before checkout — if your channel is stale, the merchant’s sales reports inherit the discrepancy.

201 Created

{
  "data": {
    "id": 51023,
    "storeId": 1,
    "status": 1,
    "orderType": 3,
    "totalAmount": 11.81
  }
}

Creating an order with status: 1 publishes a realtime event to the store’s POS and kitchen screens immediately. Use status: 0 to stage a draft that staff will not see yet.

Follow the order

curl -s "$API_BASE_URL/online-orders/51023/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": {
    "id": 51023,
    "status": "accepted",
    "statusCode": 1,
    "accepted": true,
    "foodReady": false,
    "prepTimeMinutes": 18,
    "updatedAt": "2026-07-29T09:32:11.004Z"
  }
}

Acceptance and food-ready are separate flags layered on the order’s lifecycle state, not values of it. See order lifecycle for the full state table and polling guidance.

Listing orders

curl -s "$API_BASE_URL/online-orders?storeId=1&status=1&fromDate=2026-07-29&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Parameter	Notes
storeId	One or more store ids, comma-separated
status	0 failed or draft, 1 active, 2 completed, 3 cancelled
customerId	Orders for one customer
type	Order type filter — note this uses a different numbering from orderType on create
fromDate / toDate	Order date window, YYYY-MM-DD
search	Matches order number, customer name and phone
page, limit, sort, order	Standard paging