Let's Pizza Developersv1.0.0

Get started

Authentication and keys

Every call carries a partner key in the Authorization header. The key says who you are, in which environment, and what you may do.

HTTP
GET /partner/v1/me HTTP/1.1
Host: <base address>
Authorization: Bearer lpk_test_…

We keep only a SHA-256 hash of the key; it can never be shown again. If you lose it, ask for a new one.

OAuth 2.0 instead of the fixed key#

For systems that prefer OAuth: ask for an access token with client_credentials, where client_id is your key’s id (key.id of GET /partner/v1/me) and client_secret is the key itself, in a JSON or form body, or with HTTP Basic. You get a bearer token lpt_… valid for one hour (never past the key’s own end) with the key’s scopes; send it as Authorization: Bearer, exactly like the key.

curl · HTTP Basic
curl -sS -u "$LP_KEY_ID:$LP_API_KEY" \
  -d grant_type=client_credentials \
  "$LP_BASE_URL/partner/v1/oauth/token"
curl -sS -X POST "$LP_BASE_URL/partner/v1/oauth/token" \
  -H "Content-Type: application/json" \
  --data '{
  "grant_type": "client_credentials",
  "client_id": "key_01JD5ZC9",
  "client_secret": "lpk_test_…"
}'
200 · PartnerTokenResponse
{
  "access_token": "lpt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "branches:read catalog:read catalog:write availability:write orders:read orders:ack orders:status orders:cancel orders:events payments:read reports:read webhooks:manage mappings:write"
}
  • Revoking the key stops its tokens at once.
  • A refusal carries its reason in detail.error: invalid_client · unsupported_grant_type · invalid_request.
  • Fetch a new token a minute before expires_in runs out; never one per call.

Environments never mix#

PrefixEnvironmentWorks on
lpk_test_…sandboxThe sandbox only
lpk_live_…liveProduction only

A key sent to the other environment is refused with 401 KEY_ENVIRONMENT_MISMATCH. A test configuration can never touch production by mistake. More on environments.

Scopes#

Each key carries a list of scopes. Read scopes never change anything; each write scope opens one family of calls. A call without the scope it needs is refused with 403 SCOPE_REQUIRED, and the scopes it needs are in detail.required.

ScopeWhat it allowsDefault for
branches:readRead the branches the key may act on: names, location, fulfilment, pause, and your code for each.ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleetOrdering marketplaceAccountingAnalyticsOther
catalog:readRead the published menu: categories, items, sizes, options and prices, with your codes for what is mapped.ERPPoint of sale (POS)Kitchen display (KDS)Ordering marketplaceAnalytics
catalog:writeSend the menu from your system (when it is the menu source). Saved as a draft or published per the publish policy.ERP
availability:writeSwitch an item or option off at a branch when it runs out, and back on. Never clears a flag set by branch staff.ERPPoint of sale (POS)
orders:readRead orders: new orders by pulling, and any order of your branches.ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleetAccountingAnalytics
orders:ackAcknowledge that an order reached your system, with your own number for it.ERPPoint of sale (POS)Kitchen display (KDS)
orders:statusReport order statuses (accepted, preparing, ready, out for delivery…) within the statuses allowed to you.ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleet
orders:cancelAsk to cancel an order: the customer called the branch, or the kitchen cannot make it.ERPPoint of sale (POS)
orders:eventsRecord facts on an order without moving it, such as a receipt issued or cash collected at the door.ERPPoint of sale (POS)Delivery fleet
payments:readRead how an order is paid, what was collected and what was refunded.ERPPoint of sale (POS)Accounting
reports:readRead the daily reconciliation reports: order counts and amounts per branch.ERPAccountingAnalytics
webhooks:manageManage your own webhook subscriptions: addresses, events and branches.ERPPoint of sale (POS)Delivery fleetOrdering marketplaceAccounting
mappings:writeSend the mapping between Let's Pizza ids and your system's codes (branches, items, options, tenders).ERPPoint of sale (POS)Kitchen display (KDS)

The last column is what a new key of each kind gets unless we choose otherwise. We issue keys with the fewest scopes your system needs.

Branches#

A key can be limited to some branches (up to 200). A null key.branches means every branch. A call about a branch outside the list is refused with 403 BRANCH_NOT_ALLOWED.

IP allowlist#

On request we limit a key to given IP addresses or CIDR blocks (up to 50 entries). Send us the fixed outbound addresses of your servers. A call from any other address is refused with 403 IP_NOT_ALLOWED. An empty list means anywhere.

Rate limits#

Each key has a number of requests per minute (between 10 and 6000), shown in key.ratePerMinute. Every authenticated answer carries:

HTTP
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42

Over the limit the answer is 429 RATE_LIMITED with Retry-After (also in detail.retryAfterSeconds). Wait that long, then retry; never retry at once.

Rotation and expiry#

A key may carry an end date (up to 730 days), in key.expiresAt. After it the key is refused with 401 KEY_EXPIRED.

  1. Ask for a second key for the same environment.

    Both keys work side by side: no downtime.
  2. Deploy the new key in your system.

    Check with GET /partner/v1/me that key.id is the new one.
  3. Ask us to revoke the old key.

    It stops at once; any call with it is refused with UNAUTHENTICATED.

Order of checks#

  1. A known, unrevoked key; else UNAUTHENTICATED (401).
  2. The key's environment is the host's; else KEY_ENVIRONMENT_MISMATCH (401).
  3. Not expired; else KEY_EXPIRED (401). The partner is active; else PARTNER_SUSPENDED (403).
  4. The address is in the allowlist, if any; else IP_NOT_ALLOWED (403).
  5. Within the rate; else RATE_LIMITED (429).
  6. Carries the call's scopes; else SCOPE_REQUIRED (403).