Getting started

This walkthrough takes you from no account to a live write against a sandbox merchant. Everything below happens in the developer console except the last two steps, which you run from your own backend.

Before you begin

You need a work email address you control, a backend that can keep a secret, and — if you are integrating for a specific merchant — that merchant’s LithosPOS company ID. Sandbox work needs none of the above beyond the email.

1. Create a developer account

   Sign up at developer.lithospos.com/console with your name, work email and a password. LithosPOS emails you a verification link; the account cannot sign in until you open it.

   Developer accounts are separate from merchant back-office accounts. Using the same email for both is fine — they are different identities in different systems.

2. Apply to the developer program

   Signing in for the first time drops you on the program application. Tell us who you are and what you intend to build:

   Field	Notes
   company	Legal or trading name of the business publishing the integration
   country	Where that business operates
   phone	Reachable number for the reviewer
   website	Public site or product page
   useCase	What the integration does, in a paragraph
   productInterest	Full API, Online Order API, ADSR API — pick all that apply

   Submitting moves your account to NDA_SUBMITTED. A LithosPOS reviewer approves or declines, and you are emailed either way. Applications are usually answered within two business days.

3. Sign the developer agreement

   Once approved, the console shows the current developer agreement. Read it, tick the acknowledgement box and type your full name to sign. The signature is recorded with your name, IP address, user agent and the agreement version.

   Your account becomes ACTIVE and the rest of the console unlocks. If LithosPOS publishes a newer agreement version later, GET /api/v2/developer/me returns agreementPending: true and the console asks you to sign again before further changes.

4. Create an organization

   An organization owns apps, sandbox merchants and teammates. Create one with a name; the slug is derived from it. You are its OWNER.

   Invite teammates from Members with a role — ADMIN (manage apps and credentials), DEVELOPER (read credentials metadata, submit reviews) or VIEWER (read only).

5. Create an app

   In Apps → New app, give the app a name, a one-line description, and choose its product: Full API, Online Order API or ADSR API.

   Product is permanent

   The product fixes the scope bundle the app’s tokens carry. It cannot be changed after creation — attempting it returns developer.product_immutable. Create a second app if you need a different surface.

   Creating the app immediately issues a sandbox credential:

   Shown once — copy it now

   client_id      lp_app_sbK2m9Qx7Rt4
   client_secret  lp_sk_sb_5ZkQ5vJ2rN8pXw3TfM6bD1yH4sC7aE0g

   The secret is hashed the moment it is stored. There is no endpoint that reads it back — if you lose it, rotate the credential and use the new one.

6. Provision a sandbox merchant

   Go to Sandbox and provision a merchant with a label (for example Coffee chain — QA) and a country. LithosPOS creates a real, fully provisioned demo company and returns its companyId plus a back-office login you can use to inspect what your calls did:

   Shown once

   companyId      104271
   ownerEmail     you+acme-sb1@example.com
   ownerPassword  7Kq2Xd9MvR3nT4wB

   Each organization can hold three active sandbox merchants; a fourth returns developer.sandbox_limit. Sandbox companies are flagged as demo data and are the only companies a sandbox token may touch.

7. Mint an app token

   From your backend, exchange the client credentials for an access token. With exactly one sandbox merchant in the organization, merchant_id is optional — the token endpoint resolves it for you. With more than one, it is required.

   curl

   curl -s https://api-v2.lithospos.com/v1/token \
     -H 'Content-Type: application/json' \
     -d '{
       "client_id": "lp_app_sbK2m9Qx7Rt4",
       "client_secret": "lp_sk_sb_5ZkQ5vJ2rN8pXw3TfM6bD1yH4sC7aE0g",
       "merchant_id": 104271
     }'

   JavaScript

   const response = await fetch('https://api-v2.lithospos.com/v1/token', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       client_id: process.env.LITHOSPOS_CLIENT_ID,
       client_secret: process.env.LITHOSPOS_CLIENT_SECRET,
       merchant_id: 104271,
     }),
   });
   
   if (!response.ok) {
     const { error } = await response.json();
     throw new Error(`${error.code}: ${error.message}`);
   }
   
   const { access_token, expires_in, api_base_url } = await response.json();

   200 OK

   {
     "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjYtMDQifQ…",
     "token_type": "Bearer",
     "expires_in": 900,
     "scope": "stores.read items.read items.write categories.read …",
     "api_base_url": "https://api-v2.lithospos.com/v1/"
   }

   Two fields drive everything that follows: access_token is your bearer token for the next 900 seconds, and api_base_url is the base every partner request is built from. It is one global host — the gateway reads the merchant’s region from the token and routes for you — but read it from the response rather than hard-coding it. See Authentication for caching and rotation rules.

8. Create your first item

   Point the request at api_base_url and send the token as a bearer credential.

   curl

   curl -s "https://api-v2.lithospos.com/v1/items" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Accept-Language: en' \
     -d '{
       "item": "Flat White",
       "groupId": 12,
       "brandId": 1,
       "uomId": 1,
       "taxId": 3,
       "rate": 3.75,
       "barcode": "8901234567890"
     }'

   JavaScript

   // api_base_url always ends in a slash, so relative resolution is safe.
   const endpoint = new URL('items', api_base_url);
   
   const response = await fetch(endpoint, {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${access_token}`,
       'Content-Type': 'application/json',
       'Accept-Language': 'en',
     },
     body: JSON.stringify({
       item: 'Flat White',
       groupId: 12,
       brandId: 1,
       uomId: 1,
       taxId: 3,
       rate: 3.75,
       barcode: '8901234567890',
     }),
   });
   
   const { data } = await response.json();
   console.log('created item', data.id);

   201 Created

   {
     "data": {
       "id": 8841,
       "item": "Flat White",
       "groupId": 12,
       "brandId": 1,
       "uomId": 1,
       "taxId": 3,
       "rate": 3.75,
       "status": 1
     }
   }

   groupId, brandId, uomId and taxId are required and must reference rows that exist in that merchant. Read them first from /v1/categories, /v1/brands and /v1/taxes.

   You never send a user id

   The underlying LithosPOS services stamp an actor on every write. On the partner API that actor is your app, derived from the token — do not send userId in payloads.

9. Read it back

   curl -s "https://api-v2.lithospos.com/v1/items?search=Flat%20White&limit=10" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

   200 OK

   {
     "data": [{ "id": 8841, "item": "Flat White", "rate": 3.75, "status": 1 }],
     "meta": { "page": 1, "limit": 10, "total": 1 }
   }

   Sign in to the sandbox merchant’s back office with the credentials from step 6 and you will see the same item in the catalogue.

What to do next

• Authentication — token caching, rotation, IP allowlists, sandbox versus production.
• Errors — the envelope and the full list of stable codes.
• Your product guide: Full API, Online Order API or ADSR API.
• Go-live checklist — what app review asks for.