Licenses & Entitlements

The contract side of the model — the License a customer bought, one version of a product; the typed Entitlements in your catalog; and the grant that carries the value and its enforcement between them.

A License is what a customer bought. An Entitlement is a typed right in your catalog. The grant between them — the value a given License gives for a given Entitlement, and how strictly that value is enforced — is the contract Kaiten enforces, evaluates flags against, and audits. Three levels, three questions:

License — what a customer bought

A License is one version of a product, with a type — DEVELOPMENT, TRIAL, PAID, or COMMUNITY — and instances attached to it. The product is a License family, whose slug stays put while versions are added: Kaiten Sushi Shop sells three families, starter, standard, and premium. A new version is created by naming its family; the name is a display label, and repeating one opens a second product.

Each version is a draft, published, or archived — withdrawn from sale, so it can no longer be assigned, while the instances already on it keep it. Premium shows all three: v1 archived, and still run by Kappa Kyoto; v2 on sale; v3 in preparation. A family serves its default version, or else its newest published one — there is one default per family, and none for the organization as a whole — so "Premium" can evolve while every instance stays pinned to the version it was sold.

A version that an instance runs under cannot be deleted; archiving it withdraws it from sale and leaves its instances in place. License Types covers families, the lifecycle, and the default version.

The word is deliberate — a License is the modeled, revocable, auditable object that grants rights, not a marketing tier or a billing product. See License, not Plan.

Entitlement — a typed right in the catalog

An Entitlement declares what can be granted and how it is measured. Four types:

BOOLEAN — included or not. delivery-tracking.
NUMBER — a measurable quota. menu-items, monthly-orders, delivery-drivers, locations.
CONFIG — a structured value your product reads. support-tier carries the support channels and response commitment of each tier.
NUMBER_AI_CREDIT — a NUMBER for AI credits, measured and enforced by exactly the same rules.

The NUMBER family carries the measurement semantics: a mandatory aggregation method that folds each report into the total — SUM makes monthly-orders a counter, LATEST makes menu-items a gauge of the current count; COUNT, AVERAGE, MAX, MIN complete the set — a warning threshold as a percentage of the granted value (off at 0), and an optional reset period with its anchor for counters that start over every hour, day, week, month, or year. BOOLEAN and CONFIG entitlements carry none of these. Unit labels, a display order, and a user-facing switch describe how an entitlement is presented. Entitlements can be collected into groups with an aggregated usage view — delivery-drivers and delivery-tracking form the Delivery group.

The grant — one License, one Entitlement, two numbers

The grant is the row that says how much: POST /licenses/{slug}/entitlements attaches an Entitlement to a License with a typed value — { "type": "number", "value": 1000 }, { "type": "boolean", "value": true }, or { "type": "object", "value": { … } }. Premium grants delivery-tracking = true and 1,000 monthly orders; Starter grants false and 20; Standard sits between them with 100 orders, and grants delivery tracking from its second version on. An Entitlement appears at most once per License.

A NUMBER grant carries a second number, limitCapExceededOveragePercent, and the two together are the enforcement: -1 when the value is the unlimited sentinel -1; 0 for a hard cap; a positive percentage for a soft limit with a bounded allowance. Usage & Metering gives the arithmetic. Nothing about enforcement sits on the Entitlement, so one Entitlement can be unlimited on one License and hard-capped on another: Premium grants locations unlimited, Starter grants 1 as a hard cap, and all three tiers grant menu-items with three different allowances — 0 %, 10 %, 20 %.

Measurement lives on the Entitlement; the amount and its enforcement live on the grant. That split is why a single monthly-orders definition serves every tier — only the granted number and its allowance differ — and why changing how a quota resets never means editing three Licenses.

What reads the contract

Two things read the grant. Usage reporting compares each instance's consumption against it, at report time, through the instance's License. Feature flags can read it in a targeting rule through the __kaiten facts — which is how delivery-tracking-enabled turns on for Sakura Tokyo and off for Ninja Osaka without listing either customer. Every assignment and change of a grant is an event (LICENSE_ENTITLEMENT_ASSIGNED, LICENSE_ENTITLEMENT_UPDATED, LICENSE_ENTITLEMENT_UNASSIGNED), alongside the License and Entitlement lifecycle events.

Where to go next

In depth, in the Entitlements deep-dive: types, groups, metering, and the allowance arithmetic under usage and thresholds. Building the three tiers grant by grant: Pricing Tiers.

Exact reference: data model.