Online Order API overview

The Online Order API is for software that takes orders somewhere else and hands them to a LithosPOS store: your own web shop or app, a marketplace, an aggregator, a kiosk, a voice-ordering system.

It is the same endpoints the Full API exposes, with a bundle narrowed to ordering. An Online Order app cannot touch purchasing, inventory or the merchant’s reports — which is exactly why merchants agree to connect one quickly.

Menu sync Pull stores, menus, items and modifiers, and keep your channel in step.

Order flow Create an order and follow acceptance, prep time and food-ready state.

Scope bundle

Scope	Grants
stores.read	List the merchant’s stores
menus.read	Menus, their timings and their item selection
items.read	Item names, prices, flags and descriptions
categories.read	Category structure for your channel’s navigation
modifiers.read	Modifier groups and options
online_orders.read	Read orders and their status
online_orders.write	Create orders
customers.read	Look up an existing customer before creating one
customers.write	Create or update the ordering customer

Anything outside this list returns 403 partner.scope_denied. There is no way to widen a bundle — an integration that also needs stock or reports needs a Full API app.

What “open” means

Any developer in the program can create an Online Order app; there is no product-level gate the way there is for the Full API. Production merchants still require app review and a grant per merchant, as they do for every product.

The shape of an integration

1. Discover the merchant’s stores — GET /v1/stores.
2. Sync the menu for each store you list — GET /v1/menus then /menus/:id/full.
3. Match or create the customer — GET /v1/customers?mobile=…, then POST if new.
4. Create the order — POST /v1/online-orders. The store’s POS and kitchen screens are notified in realtime.
5. Follow it — GET /v1/online-orders/:id/status until it is ready or done.

A complete first call

# 1. Which stores does this merchant run?
curl -s "$API_BASE_URL/stores" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. What can store 1 sell online right now?
curl -s "$API_BASE_URL/menus?storeId=1&online=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Send an order to it
curl -s "$API_BASE_URL/online-orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "storeId": 1,
    "orderType": 2,
    "customerName": "Priya Nair",
    "customerPhone": "+919845012345",
    "takenBy": "acme-web",
    "items": [{ "id": 8841, "item": "Flat White", "qty": 1, "rate": 3.75 }]
  }'

Design rules worth knowing early

• One order, one store. storeId is on the order, not on the line. Split a basket that spans stores into separate orders.
• Prices come from you. The order carries what you charged. Re-read the menu often enough that you never charge a stale price.
• Orders are not editable. There is no update endpoint in this version. Get the basket right before you submit; corrections happen at the store.
• No webhooks yet. Follow orders by polling /status. See order flow for a sane polling cadence.