Reservation API overview

The Reservation API is for software that takes table bookings somewhere else and hands them to a LithosPOS store: your own booking widget or app, a reservation marketplace, a concierge or hotel desk, a guest CRM.

It is the same endpoints the Full API exposes, with a bundle narrowed to bookings. A Reservation app cannot see the menu, stock, sales or reports — only the stores, the guests it books for and their reservations — which is exactly why merchants agree to connect one quickly.

Reservations Create bookings, the status lifecycle, the store's booking rules and every error code.

Customers Find the guest by mobile before you book, or create them.

Scope bundle

Scope	Grants
stores.read	List the merchant’s stores, so the guest can pick one
customers.read	Look up an existing guest before creating one
customers.write	Create or update the guest you are booking for
reservations.read	List and read bookings and their status
reservations.write	Create bookings and move them through their lifecycle

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

What “open” means

Any developer in the program can create a Reservation 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. Match or create the guest — GET /v1/customers?mobile=…, then POST /v1/customers if new.
3. Book the table — POST /v1/reservations. The store’s reservation list shows it straight away.
4. Follow it — GET /v1/reservations/:id, or the day’s list for a store, as the host confirms, seats and completes it.
5. Change it when the guest does — PATCH /v1/reservations/:id with a new time, party size or cancelled.

A complete first call

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

# 2. Is the guest already a customer?
curl -s "$API_BASE_URL/customers?mobile=%2B919845012345" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Book a table for four at store 1
curl -s "$API_BASE_URL/reservations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": 5521,
    "storeId": 1,
    "reservationDate": "2026-10-24",
    "reservationTime": "19:30",
    "partySize": 4,
    "occasion": "Anniversary",
    "note": "Window table if possible"
  }'

201 Created

{
  "data": { "reservationId": 318 }
}

Design rules worth knowing early

• Always send storeId. Only a single-store merchant falls back to its one store; on a multi-store merchant a booking without a store shows up at every store.
• Date and time are the store’s clock. Send 19:30 for a 7:30 pm table. Do not convert to UTC.
• The rules belong to the merchant. Party sizes, how far ahead, minimum notice and capacity are set per store; a booking that breaks one comes back with a code and the limit in params. Show it to the guest instead of hard-coding limits. See booking rules.
• The host moves bookings too. Staff confirm, seat and complete bookings at the store. Read before you change a status, and treat reservations.invalid_status_transition as “someone got there first”.
• No webhooks yet. Follow bookings by reading them. For a host-stand view, list one store’s day: ?storeId=1&fromDate=<day>&toDate=<day>&order=asc.
• Creates are not idempotent. If a create times out, list the guest’s bookings for that date before you try again.

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.