Glossary
Short definitions of terms that appear frequently in the HummyTummy API and docs.
Tenant
The top-level account that represents a restaurant business (customer account).
It owns the licence, the purchased catalog products, and all data. Tenant
resolution is done via the tenantId in the JWT, not by host name.
Branch
A physical location/branch belonging to a tenant. Tables, orders, stock, and
most operational data are tied to a branch. Branch-scoped endpoints require the
X-Branch-Id header.
Role
A user’s permission level. Roles: ADMIN, MANAGER, WAITER, KITCHEN,
COURIER. WAITER, KITCHEN, and COURIER are “hard-restricted” roles —
they are pinned to a single branch (a primaryBranchId is mandatory) and
cannot target any other branch.
KDS (Kitchen Display System)
The screen that mirrors incoming orders to kitchen/prep stations in real time.
Depends on the kdsIntegration feature.
POS (Point of Sale)
The till interface for taking orders, payments, and managing tables. Depends on
the posAccess feature.
QR menu
The public menu and ordering interface a guest reaches by scanning the QR code at the table. It drives the ordering and self-pay flows through an ordering session.
Self-pay
A guest paying their own bill from their own device (or the table screen),
without a waiter. It runs by creating a PayTR hosted-iframe pay intent and
requires the payments:write scope.
Scope
A unit of permission carried by a partner API key and a screen token
(e.g. menu:read, orders:write). Each /display endpoint requires a
specific scope. See Partner Scopes.
Screen token
An access token minted from a partner API key and bound to a specific screen/device session. It is bound to a tenant, an optional table, and a branch; its effective scopes are a subset of the parent key’s.
Webhook
An event notification sent outward from the server. For example, the PayTR
payment provider’s callback reporting a payment result; a payment is only
provisioned after the webhook confirms it (confirmAndProvision).
Outbox
A pattern where an event record is written in the same transaction as the database change and then reliably published afterwards. It keeps side effects (event publication) atomic with the primary data and provides at-least-once delivery.
Entitlement
The effective set of features, limits, and integrations derived from a tenant’s
free core plus the catalog products it has bought. feature.* folds with
OR, limit.* with SUM, integration.* with UNION; the set is recomputed
(re-projected) whenever a product is bought, cancelled, or lapses. Gates consult
it through @RequireEntitlement and return 403 ENTITLEMENT_REQUIRED when it
is missing. See the Entitlement Matrix.
Catalog product (add-on)
A module, integration, capacity unit, credit pack, or service bought
individually on top of the free core. It is defined in the marketplace catalog,
bought through the PayTR checkout rail, and its grants map joins the
entitlement set once payment is confirmed. The ownership row is TenantAddOn.
Licence
The annual product (license_annual) that is the prerequisite for every paid
capability. It is required both to buy and to use: while it is not live, the
grants of every requiresLicense product are suppressed — ownership rows and
business data are untouched, and paying the licence re-lights everything.
Credit
A prepaid consumption balance (PHOTO, VIDEO, MODEL3D, SMS). It is not
an entitlement: it is bought as a one-time pack, never expires, and is valid
until consumed. The balance is read live at spend time; when it is insufficient
the call returns 402 QUOTA_EXCEEDED.
Anniversary
The tenant-local calendar day the licence was bought — the account’s immutable renewal date. Every annual item bought later is prorated to the days remaining until it, so the whole account renews on one date with one invoice. Renewal is manual: there is no card vault and no auto-charge.