Sandbox merchants

A sandbox merchant is a real LithosPOS company created by the same provisioning pipeline as a paying customer, flagged as demo data and owned by your organization. It has its own database, its own back office and its own ids. You can write to it freely.

Provision one

From Sandbox → Provision merchant, give it a label and a country. LithosPOS creates the company and returns credentials once:

Shown once

companyId      104271
label          Coffee chain — QA
ownerEmail     you+acme-sb1@example.com
ownerPassword  7Kq2Xd9MvR3nT4wB

The owner email is a plus-addressed alias of your own developer email, so verification and password-reset mail reaches your inbox. Sign in to the merchant back office with those credentials to see the effect of your API calls in the product itself.

Each organization can hold three active sandbox merchants. A fourth returns developer.sandbox_limit; deactivate one you no longer need first.

Grants are automatic

Sandbox access needs no approval. When you provision a merchant, LithosPOS creates a sandbox grant for every app in the organization, and when you create a new app it is granted against every existing sandbox merchant. That is why merchant_id is optional at mint time when the organization has exactly one sandbox merchant.

Deactivating a sandbox merchant revokes its grants. Existing tokens keep working until they expire — up to 900 seconds — and then stop.

The environment rule

Environment consistency is enforced in both directions and cannot be overridden:

• A sandbox credential (lp_app_sb…) may only reach companies flagged as demo data.
• A production credential (lp_app_pk…) may only reach companies that are not.

Violations fail at mint time with developer.env_mismatch. This is what stops a half-configured test harness from writing into a live restaurant.

What you start with

Sandbox merchants are provisioned from the same baseline as new customers, so they arrive with a standard starting configuration rather than an empty database. Discover it before you assume ids:

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

Build the rest of the fixture — categories, brands, taxes, items, menus, customers — through the API. Doing it that way doubles as an integration test of your own write paths.

What sandbox does not simulate

Area	Behaviour
Payments	No card processing. Sales carry payment types but no acquirer is involved
Hardware	No terminals, printers or KDS screens are attached unless you pair them yourself
Load	Sandbox clusters are sized for development. Do not use them for load testing
Longevity	Demo data may be reset during platform maintenance. Never treat it as durable storage
Merchant identity	Sandbox company ids are not related to any live merchant id

Test the failure paths too

Sandbox is the only safe place to exercise the error surface: send an unknown groupId to get db.not_found, repeat a barcode to get db.duplicate, request a 90-day report window to get partner.window_too_large, and burst past 300 requests to see partner.rate_limited and the reset headers. Handle those before review, not after.

Moving to production

Sandbox and production credentials are separate objects — you do not “promote” a sandbox key. When your app is approved, LithosPOS issues a production credential and creates grants for the merchants you are authorised to serve. Your code should read both the client id and the secret from configuration so the only change is an environment variable.

Read the go-live checklist for what review expects to see.