Entitlement Matrix

This page summarises the one mechanism that decides what a business can reach: entitlement keys and who grants them.

There are no plans, tiers, or bundles. The core product is free forever; paid capabilities are bought individually from the catalog, and each product joins the entitlement set through the keys it grants (grants).

Key namespace and the fold

The entitlement set is the fold of grant rows coming from several sources. The combine rule depends on the key prefix:

There are three grant sources: free:baseline (the free core), addon:<code>:<id> (one source per owned product), and override:admin (superadmin intervention; for limit.* / integration.* it can replace the running value via the { __replace: … } wrapper).

The free core (free:baseline)

Projected for every tenant, unconditionally, forever, with no licence required.

The rest of the free core (menu management, tables and floor plan, QR menu, order management, cash drawer, basic reports, team and roles, customers, the device and branch panel) is not tied to any entitlement key at all — those routes carry no @RequireEntitlement. Entitlement gates are opt-in per route; a route without the decorator denies nobody.

Catalog products and what they grant

Prices are TRY, VAT-inclusive, and stored in the catalog as cents (priceCents): 490000 = ₺4,900.00. annual lines are day-prorated to the account anniversary — see the Licensing & Billing API.

Licence

Modules

Integrations

Capacity

maxQuantity: 100. Bought by the unit: the projector multiplies the limit.* value by the row’s quantity, and the engine sums that on top of the free baseline’s 1.

Credits (one-time, no expiry)

Credit packs grant no entitlement (grants: {}); they top up a balance that is valid until consumed. A dependency can be satisfied by an active product the tenant already owns or by a sibling line in the same cart.

Service

Licence suppression

While the licence is not live, the grants of every requiresLicense: true product are withheld. The projector still writes the ownership source (so the owned-products list stays complete) but with an empty grant array.

• No business data is deleted: stock, reservations, personnel, generated AI media and chargedCents all stay put. Paying the licence back re-lights everything on the next projection.
• The cart-level LICENSE_REQUIRED check stops the sale; this is what stops access — which is what matters when a business renews some lines of its anniversary invoice but not the licence itself.
• A past_due row keeps granting for 7 days (ADDON_GRACE_DAYS); the entitlement drops when the sweeper flips the row to expired. active rows get the same 7-day horizon, so nobody is locked out for the hours between the engine’s 5-minute expiry sweep and the daily sweeper on anniversary night.

Reading entitlements

/v1/entitlements/me and /v1/me/licensing are tenant-level and do not expect X-Branch-Id.

Entitlement denial (403)

A gated route returns a 403 carrying the missing entitlement and the product that unlocks it:

{
  "statusCode": 403,
  "message": "Bu özellik hesabınızda etkin değil.",
  "error": "Entitlement Required",
  "errorCode": "ENTITLEMENT_REQUIRED",
  "timestamp": "2026-08-13T08:14:05.123Z",
  "path": "/api/reports/advanced",
  "requestId": "1786…-a1b2c3d4e",
  "actionable": {
    "requirement": { "type": "feature", "key": "feature.advancedReports" },
    "offer": {
      "code": "advanced_reports",
      "name": "Advanced Reports & Analytics",
      "kind": "module",
      "annualPriceCents": 129000,
      "proratedCents": 74123,
      "currency": "TRY",
      "periodEnd": "2027-03-10T00:00:00.000Z"
    },
    "licenseRequired": false,
    "reason": "not_owned"
  }
}

The remediation payload travels under actionable, through the global error filter’s allowlist (only requirement, offer, licenseRequired, reason):

• requirement.type: feature | limit | integration. A limit denial also carries usage and cap.
• offer: the cheapest product that provides the key, priced for this tenant today. The price shown and the price charged at checkout come from the same catalog read.
• licenseRequired: true means the real blocker is the missing licence, not the product — the offer switches to the licence.
• reason: not_owned (never bought) or lapsed (expired), which is what lets a client choose between “Buy” and “Renew”.

Related

• Licensing & Billing API — the checkout rail, proration, the anniversary and renewals.
• Marketplace API — catalog, purchase and cancellation endpoints.
• Error Codes — the standard error envelope and the stable errorCode values.