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 and reservations Customer records, loyalty identifiers and table bookings.

Online orders Create orders and follow them through the kitchen.

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 33 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
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.

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