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.

Going to production

Production starts with the same app review as every product. After approval, merchants connect your app themselves through OAuth. There is no access request and no API key.

1. Submit the app for review

   In the console, open Apps → your app → Review and fill in the integration description, URLs, support email, walkthrough video and privacy policy. Select Submit for review, then contact the LithosPOS team to tell them the app is waiting. See the go-live checklist for what reviewers check.

2. Register your redirect URIs

   When the app is APPROVED, LithosPOS issues its production credential: a lp_app_pk… client id and a secret shown once. Under Apps → your app → OAuth, register up to five exact-match https:// redirect URIs for your Connect LithosPOS button.

3. Connect each merchant with OAuth

   • Your Connect LithosPOS button redirects the merchant to https://my.lithospos.com/oauth/authorize with your client_id, redirect_uri and a state value.
   • The merchant’s account owner signs in and approves your app on the consent screen.
   • LithosPOS redirects back to your URI with code, state and merchant_id.
   • Your backend exchanges the code at POST /v1/oauth/token within five minutes. You get a 900-second access token and a refresh token.
   • Call the API with Authorization: Bearer <access_token>. Refresh before it expires, and save the new refresh token each time, because it rotates on every use.

Adding another merchant later is another consent, not another review. A merchant can disconnect you at any time from Settings → Connected apps. The full flow, PKCE, refresh rules and error codes are in Connect merchants with OAuth.