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.

Testing the OAuth flow

Sandbox is not limited to the client-credentials quickstart. The full merchant consent flow runs against sandbox tenants, at the same URL a live merchant uses, so you can build and demo your Connect LithosPOS experience before review.

Three things make it work:

• Your sandbox client id. lp_app_sb… is accepted at https://my.lithospos.com/oauth/authorize whatever state the app’s review is in. It will only consent against sandbox tenants belonging to your own organization.
• The sandbox owner login. The consent screen is a merchant surface, so sign in with the ownerEmail / ownerPassword that provisioning gave you — not your developer console account. Only the account owner can approve.
• Loopback redirect URIs. http://localhost:3000/callback and http://127.0.0.1[:port] are accepted alongside https:// URIs, so the redirect can land on your dev server. Add them to the app’s redirect URI list first; matching is exact.

https://my.lithospos.com/oauth/authorize
  ?response_type=code
  &client_id=lp_app_sbK2m9Qx7Rt4
  &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback
  &state=e3b0c44298fc1c149afbf4c8996fb924

Refresh rotation, the 60-second grace window, reuse detection and revocation all behave exactly as they do in production — sandbox refresh tokens are simply lp_rt_sb_…. Test the family-revocation path here, where losing a connection costs nothing.

ADSR apps have nothing to set up: sandbox tenants are auto-granted, so a lp_ak_sb_… API key reads them immediately.

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 live merchants authorize it themselves: through consent for Full API and Online Order API apps, through an access request for ADSR. Your code should read the client id, the secret and the redirect URI from configuration so the only change is an environment variable.

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