Entitlement Types

Overview

Every entitlement has a type, set at creation and immutable afterwards. The type fixes two things: the shape of the value a License grants, and whether the entitlement is measured at all. Only the NUMBER family is metered; a BOOLEAN or CONFIG value is read by your product, never reported against.

Examples use $KAITEN_API and $KAITEN_TOKEN as set up in the quickstart, and the Kaiten Sushi Shop catalog. On a stack seeded with the demo data these entitlements and their grants already exist with the definitions shown — sending one again returns 409 Conflict; read them instead. Slugs are kebab-case: the API refuses an underscore in a slug.

BOOLEAN

Included, or not. Used for feature gates that a flag rule or your product reads.

Grant value:

{ "type": "boolean", "value": true }

Kaiten Sushi Shop: delivery-tracking — false on Starter, true on every version of Premium, and the one entitlement that differs between the two versions of Standard: false on standard, the version the family serves, true on standard-v2. The delivery-tracking-enabled flag reads the grant, so the feature follows the License version without listing a single customer.

curl -X POST "$KAITEN_API/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery Tracking",
    "slug": "delivery-tracking",
    "description": "Real-time delivery tracking for end customers.",
    "type": "BOOLEAN",
    "groupSlugs": ["delivery"]
  }'

curl -i -X POST "$KAITEN_API/licenses/premium-v2/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entitlementSlug": "delivery-tracking",
    "value": { "type": "boolean", "value": true }
  }'

NUMBER

A measurable quota. The entitlement declares how the quota is measured; each grant declares how much a License gives and how strictly that number is enforced.

Grant value:

{ "type": "number", "value": 20 }

-1 is the unlimited sentinel — a grant of -1 is never exceeded.

Kaiten Sushi Shop: monthly-orders (a SUM counter that resets every calendar month), menu-items, delivery-drivers, and locations (three LATEST gauges — each report states the current count).

curl -X POST "$KAITEN_API/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Orders",
    "slug": "monthly-orders",
    "description": "Orders a restaurant can process per month.",
    "type": "NUMBER",
    "aggregationMethod": "SUM",
    "resetPeriod": "MONTH",
    "resetAnchor": "CALENDAR",
    "groupSlugs": ["restaurant-operations"],
    "icon": "lucide:shopping-cart",
    "unitSingular": "order",
    "unitPlural": "orders",
    "userFacing": true,
    "displayOrder": 2
  }'

curl -i -X POST "$KAITEN_API/licenses/starter/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entitlementSlug": "monthly-orders",
    "value": { "type": "number", "value": 20 },
    "limitCapExceededOveragePercent": 0
  }'

What the entitlement carries — the measurement, identical for every License:

What the grant carries — the contract, per License:

The seeded grants read the same entitlement three ways: Starter caps monthly-orders at 20 with 0 (hard cap), Standard grants 100 with 10, Premium 1,000 with 20. Usage & Thresholds carries the arithmetic; Metering the aggregation methods and the windows.

NUMBER_AI_CREDIT

A NUMBER whose unit is AI credits. It is a distinct type so that your catalog and your pricing pages can tell credits apart from other quotas — and so that the AI Control Plane Coming soon can build on it — but it is created, granted, measured, and enforced under exactly the NUMBER rules: an aggregation method is mandatory, the grant carries limitCapExceededOveragePercent, the same three values mean the same three things, and a report above the maximum allowed usage is refused the same way.

curl -X POST "$KAITEN_API/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Menu Copywriting Credits",
    "slug": "menu-copy-credits",
    "description": "AI credits for generated dish descriptions.",
    "type": "NUMBER_AI_CREDIT",
    "aggregationMethod": "SUM",
    "resetPeriod": "MONTH",
    "resetAnchor": "CALENDAR"
  }'

Kaiten Sushi Shop's seeded catalog has no AI-credit entitlement; the one above is an addition you can make next to it.

CONFIG

A structured value — a JSON object your product reads as-is. Used for settings that vary by License and are not a number or a switch.

Grant value:

{ "type": "object", "value": { "tier": "priority", "channels": ["email", "slack"], "response_sla_hours": 4 } }

Kaiten Sushi Shop: support-tier — the support channels and response commitment of each License (community, standard, priority), read by the product's help center.

curl -X POST "$KAITEN_API/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Tier",
    "slug": "support-tier",
    "description": "Support channel and response commitment for the restaurant.",
    "type": "CONFIG",
    "groupSlugs": ["restaurant-operations"]
  }'

curl -i -X POST "$KAITEN_API/licenses/premium-v2/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entitlementSlug": "support-tier",
    "value": {
      "type": "object",
      "value": { "tier": "priority", "channels": ["email", "slack"], "response_sla_hours": 4 }
    }
  }'

Comparison

Entitlement properties

The body of POST /entitlements; PUT /entitlements/{slug} takes the same fields minus slug, and rejects a changed type, aggregationMethod, resetPeriod, or resetAnchor.

Exact reference — columns and CHECK constraints: the entitlement table.