Full API overview

The Full API exposes the whole back-office surface of a LithosPOS merchant. It is the right product for ERP and accounting connectors, catalogue management tools, inventory systems, CRM integrations and any vertical application that needs to both read and write merchant data.

Approval required

Full API apps can create sandbox credentials immediately, but production credentials are issued only after app review. Build and test against a sandbox merchant first.

Domains

Catalogue Items (standard, variant, composite), categories, brands, units, kitchens, modifiers, menus and combo meals.

Inventory Stock adjustments, transfers between stores, recipes and productions.

Purchasing Purchase orders and goods receipt.

Customers Customer records, loyalty identifiers and credit terms.

Reservations Table bookings, the status lifecycle and the store's booking rules.

Online orders Create orders and follow them through the kitchen.

Table orders and payments Put orders on a table, read the open bill and record the guest's QR payment.

Taxes Tax rows, rates and how they attach to items.

Reports Business summary, item sales, payment types and the sales list.

Scope bundle

A Full API token carries all 35 scopes. You do not request scopes per call — the product resolves the bundle at mint time and the token carries the result.

Domain	Scopes
Stores	stores.read
Items	items.read, items.write
Categories	categories.read, categories.write
Brands	brands.read, brands.write
Menus	menus.read, menus.write
Modifiers	modifiers.read, modifiers.write
Meal slots	meal_slots.read, meal_slots.write
Purchase orders	purchase_orders.read, purchase_orders.write
Stock transfers	stock_transfers.read, stock_transfers.write
Stock adjustments	stock_adjustments.read, stock_adjustments.write
Recipes	recipes.read, recipes.write
Productions	productions.read, productions.write
Customers	customers.read, customers.write
Reservations	reservations.read, reservations.write
Taxes	taxes.read, taxes.write
Online orders	online_orders.read, online_orders.write
Tables	tables.read
Table payments	payments.write
Reports	reports.read, adsr.read

A call to a route whose scope is missing returns 403 partner.scope_denied naming the scope in params.

Conventions

Paths

Every route hangs off the base URL returned as api_base_url, which is one global host for every merchant and every region:

{api_base_url}{resource}   →   https://api.lithospos.com/v1/items

List endpoints

Parameter	Type	Default	Notes
page	number	1	1-based
limit	number	10	Maximum 100
sort	string	id	Column to order by
order	asc | desc	desc
search	string	—	Free-text match on the domain’s primary label
status	number	—	1 active, 0 inactive
fromDate / toDate	string	—	Date window on document lists, YYYY-MM-DD

Report endpoints use from / to for their window rather than fromDate / toDate — they take a trading-date range, not a filter on a document list.

List response

{
  "data": [ /* rows */ ],
  "meta": { "page": 1, "limit": 25, "total": 137 }
}

Single-resource responses are { "data": { … } } with no meta.

Writes

• POST creates, PATCH updates. PATCH bodies are partial — send only what changes.
• Unknown properties are rejected with 400, so a misspelled field never silently disappears.
• Never send userId. The partner layer stamps your app as the actor on every write.
• Reference ids (groupId, brandId, taxId, storeId, uomId) must exist in that merchant. Read them first; unknown ids return db.not_found.
• PATCH bodies on items may carry nested collections (stores, variants, combo, modifierIds); a collection you send replaces the stored one — except stores, where only the rows you list are written; a collection you omit is untouched. Sending rate instead rewrites the price at every store. See catalogue.

Stores

Almost everything is scoped to a store. Read the list once and cache it:

curl -s "$API_BASE_URL/stores" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    { "id": 1, "name": "Brigade Road", "address": "12 Brigade Rd, Bengaluru", "status": 1, "type": 0 }
  ],
  "meta": { "page": 1, "limit": 10, "total": 1 }
}

type is 0 for a store and 1 for a warehouse. Warehouses hold stock but do not sell, so they appear in transfers and adjustments but not in sales reports.

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.

Not in this version

Area	Status
Price-book bulk tools and item images	Back office only. Per-store prices are set on the item itself
Outbound webhooks	Planned. Poll for now
Store and terminal administration	Merchant-managed
Writing sales or refunds	Sales are created by the point of sale; the API reads them
Per-scope consent	The merchant approves the app’s whole product bundle, not individual scopes. See OAuth