← Hub

Open Pizza core API (/v1)

Generated from the @openpizza/core zod contract. Machine-readable: /openapi.json (OpenAPI 3.1). Auth: Authorization: Bearer <core token> from POST /oauth/token; the tenant always comes from the token. Writes need Idempotency-Key. Errors are RFC 9457 problem+json with a stable code.

Tenant

OperationEndpointScopesServed by

tenant.get

The calling tenant

GET /v1/tenanttenant:readtenant source

capabilities.get

What the tenant's commerce source supports

GET /v1/capabilitiesany tokenhub

entitlements.get

Module entitlements (core.tenant_modules) + POS plan

GET /v1/entitlementsentitlements:readhub

moduleSettings.get

Per-tenant module settings

GET /v1/modules/{module}/settingsentitlements:readhub

moduleSettings.update

Patch module settings (needs <module>:admin; own module or POS)

PATCH /v1/modules/{module}/settingsIdempotency-Keyentitlements:readhub

Locations

OperationEndpointScopesServed by

locations.list

List locations

GET /v1/locationslocations:readtenant source

locations.get

Get a location

GET /v1/locations/{location_id}locations:readtenant source

Menu

OperationEndpointScopesServed by

menu.get

Resolved menu for a location (overrides + 86 folded in)

GET /v1/locations/{location_id}/menumenu:readtenant source

menu.setAvailability

86 / un-86 an item, size or modifier

PUT /v1/locations/{location_id}/menu/availabilityIdempotency-Keymenu.availability:writetenant source

menu.publishAllergens

Publish the allergen matrix (emits menu.allergens.published)

PUT /v1/catalog/allergensIdempotency-Keymenu.allergens:writetenant source

Orders

OperationEndpointScopesServed by

quotes.create

Server-priced quote (priceCart)

POST /v1/quotesIdempotency-Keyquotes:writetenant source

quotes.get

Get a quote

GET /v1/quotes/{quote_id}quotes:writetenant source

orders.list

List orders

GET /v1/ordersorders:readtenant source

orders.get

Get an order

GET /v1/orders/{order_id}orders:readtenant source

orders.create

Place an order (priced server-side; Idempotency-Key = order id)

POST /v1/ordersIdempotency-Keyorders:writetenant source

orders.cancel

Cancel an order

POST /v1/orders/{order_id}/cancelIdempotency-Keyorders:writetenant source

orders.release

Release a held order to the kitchen

POST /v1/orders/{order_id}/releaseIdempotency-Keyorders:writetenant source

orders.extendHold

Extend a held order's hold (0.3.1; creator only, capped)

POST /v1/orders/{order_id}/hold/extendIdempotency-Keyorders:writetenant source

orders.updateStatus

Move fulfillment status

POST /v1/orders/{order_id}/statusIdempotency-Keyorders:writetenant source

kitchen.load

Live kitchen load signal for a location

GET /v1/locations/{location_id}/kitchen-loadorders:readtenant source

Payments

OperationEndpointScopesServed by

payments.listForOrder

Payments for an order

GET /v1/orders/{order_id}/paymentspayments:readtenant source

payments.get

Get a payment

GET /v1/payments/{payment_id}payments:readtenant source

payments.recordExternal

Record a tender taken outside core

POST /v1/orders/{order_id}/paymentsIdempotency-Keypayments:writetenant source

payments.createSession

Create a hosted payment session (pay link) for an order

POST /v1/orders/{order_id}/payment-sessionsIdempotency-Keypayments:writetenant source

payments.getSession

Get a payment session

GET /v1/payment-sessions/{session_id}payments:readtenant source

payments.account

Processor account (Connect id) and platform fee schedule

GET /v1/payments/accountpayments:readtenant source

Customers

OperationEndpointScopesServed by

customers.list

List customers

GET /v1/customerscustomers:readtenant source

customers.get

Get a customer

GET /v1/customers/{customer_id}customers:readtenant source

customers.lookup

Find a customer by email or phone (404 when none)

GET /v1/customers/lookupcustomers:readtenant source

customers.upsert

Upsert a customer by email/phone

POST /v1/customersIdempotency-Keycustomers:writetenant source

customerAuth.start

Send a customer one-time code (SMS/email)

POST /v1/customer-auth/challengesIdempotency-Keycustomers:authhub

customerAuth.verify

Verify the code → customer + customer session token

POST /v1/customer-auth/challenges/{challenge_id}/verifycustomers:authhub

Staff

OperationEndpointScopesServed by

staff.list

List staff

GET /v1/staffstaff:readtenant source

staff.get

Get a staff member

GET /v1/staff/{staff_id}staff:readtenant source

drawerSessions.list

Cash drawer sessions (POS shifts) at a location

GET /v1/locations/{location_id}/drawer-sessionsdrawer_sessions:readtenant source

staff.setPin

Set or clear a staff member's quick-switch PIN

PUT /v1/staff/{staff_id}/pinIdempotency-Keystaff:set_pintenant source

staff.resetLoginIdentity

Forget a staff member's staff-login email binding (0.3.1; owner staff session)

POST /v1/staff/{staff_id}/login-identity/resetIdempotency-Keystaff:writehub

staff.roster

Active staff roster: ids, names, roles, locations; no contact info (0.3.3; staff:roster, clock devices)

GET /v1/staff/rosterstaff:rosterhub

staff.verifyPin

Verify a staff PIN → acting-staff session token

POST /v1/staff/verify-pinstaff:pin_verifyhub

Deliveries

OperationEndpointScopesServed by

deliveries.list

List deliveries

GET /v1/deliveriesdeliveries:readtenant source

deliveries.get

Get a delivery

GET /v1/deliveries/{delivery_id}deliveries:readtenant source

deliveries.updateStatus

Update delivery status

POST /v1/deliveries/{delivery_id}/statusIdempotency-Keydeliveries:writetenant source

Sales

OperationEndpointScopesServed by

sales.daily

Daily sales for a location

GET /v1/locations/{location_id}/sales/dailysales:readtenant source

sales.summary

Sales summary grouped by location/channel/item/hour/day

GET /v1/sales/summarysales:readtenant source

sales.hourly

Hourly sales buckets (location-local hours)

GET /v1/locations/{location_id}/sales/hourlysales:readtenant source

sales.items

Item-level sales per business date

GET /v1/sales/itemssales:readtenant source

tips.list

Normalised tip facts (tender tips vs order tips, no double count)

GET /v1/tipstips:readtenant source

Events

OperationEndpointScopesServed by

events.list

Pull feed (same envelope as webhooks), oldest first

GET /v1/eventsevents:subscribehub

events.ingest

Publish a module event (module namespace only)

POST /v1/events/ingestIdempotency-Keyevents:publishhub

Webhooks

OperationEndpointScopesServed by

webhookEndpoints.list

List webhook endpoints

GET /v1/webhook-endpointsevents:subscribehub

webhookEndpoints.create

Register a webhook endpoint (secret shown once)

POST /v1/webhook-endpointsIdempotency-Keyevents:subscribehub

webhookEndpoints.get

Get a webhook endpoint

GET /v1/webhook-endpoints/{endpoint_id}events:subscribehub

webhookEndpoints.update

Update url/types/status

PATCH /v1/webhook-endpoints/{endpoint_id}events:subscribehub

webhookEndpoints.delete

Delete a webhook endpoint

DELETE /v1/webhook-endpoints/{endpoint_id}events:subscribehub

webhookEndpoints.rotateSecret

Rotate the signing secret (old one signs for 24h more)

POST /v1/webhook-endpoints/{endpoint_id}/rotate-secretIdempotency-Keyevents:subscribehub

webhookEndpoints.replay

Replay events (by id or time range) to this endpoint

POST /v1/webhook-endpoints/{endpoint_id}/replayIdempotency-Keyevents:subscribehub

webhookEndpoints.deliveries

Delivery log for this endpoint

GET /v1/webhook-endpoints/{endpoint_id}/deliveriesevents:subscribehub

Directory

OperationEndpointScopesServed by

directory.tenants.list

Tenants that enabled the calling module

GET /v1/directory/tenantsdirectory:readhub

directory.tenants.get

Look up a tenant (that enabled the calling module) by slug

GET /v1/directory/tenants/{slug}directory:readhub

directory.locations.search

Geo search across tenants that enabled the calling module

GET /v1/directory/locationsdirectory:readhub

Devices

OperationEndpointScopesServed by

devices.createPairing

Create a one-time device pairing code (kiosk, board, terminal, KDS)

POST /v1/devices/pairingsIdempotency-Keydevices:pairhub

devices.list

Paired devices

GET /v1/devicesdevices:readhub

devices.revoke

Revoke a device credential

POST /v1/devices/{device_id}/revokeIdempotency-Keydevices:writehub

devices.createPairingOnBehalf

Create a pairing code for a signed-in staff member (0.3.2; module client + staff_token, no devices:pair)

POST /v1/devices/pairings/on-behalfIdempotency-Keyany tokenhub

devices.revokeOwn

Revoke a device your module paired (0.3.3; module client, no staff token, no devices:* scope)

POST /v1/devices/{device_id}/revoke/ownIdempotency-Keyany tokenhub

devices.revokeOnBehalf

Revoke a device for a signed-in staff member (0.3.2; module client + staff_token)

POST /v1/devices/{device_id}/revoke/on-behalfIdempotency-Keyany tokenhub

Realtime

OperationEndpointScopesServed by

realtime.publish

Nudge a realtime channel (bumps its version)

POST /v1/realtime/channels/{channel}/nudgerealtime:publishhub

realtime.subscribeToken

Client-safe subscribe token + SSE URL for a channel

POST /v1/realtime/channels/{channel}/subscribe-tokenrealtime:subscribehub

Notifications

OperationEndpointScopesServed by

notifications.send

Send an email/SMS through the hub's provider

POST /v1/notificationsIdempotency-Keynotifications:sendhub

notifications.get

Get a notification's status

GET /v1/notifications/{notification_id}notifications:sendhub

Providers

OperationEndpointScopesServed by

providers.list

Registered checkout/delivery providers

GET /v1/providersproviders:readhub

providers.register

Register (upsert) a provider for this tenant (own module key only)

PUT /v1/providers/{kind}/{key}Idempotency-Keyproviders:writehub

providers.remove

Remove a provider registration

DELETE /v1/providers/{kind}/{key}providers:writehub