Monetization

The chain

Monetization in Kaiten is one chain of four records. A License is what a customer bought. A license entitlement — the grant — is the value that License gives for one entitlement in your catalog: the contract side. An Instance is where your product runs for a customer, under exactly one License. Entitlement usage is what that instance has consumed: the observed side. Enforcement, targeting, and the audit trail all read this chain, so a commercial change is a data change, never a deploy.

License — one version of a product, with a type (DEVELOPMENT, TRIAL, PAID, COMMUNITY), a slug used in every URL, and a lifecycle state: draft, published, or archived — withdrawn from sale, kept by the instances already on it. A product's versions form a License family: a new version is created by naming the family, never by repeating a name, and the family serves its default version, or else its newest published one. Kaiten Sushi Shop sells three families with six versions between them: starter (COMMUNITY), standard (DEVELOPMENT, two versions), and premium (PAID, three). License Types covers the type, the family, the lifecycle, and the default version.

License entitlement — the join between a License and an entitlement, carrying a typed value: { "type": "number", "value": 1000 }, { "type": "boolean", "value": true }, or { "type": "object", "value": { … } }. An entitlement appears at most once per License, and each version carries its own grants. The same monthly-orders entitlement is granted at 20 on Starter, 100 on Standard, and 1,000 on Premium — the definition is written once, only the granted number differs. Pricing Tiers builds a tier from these rows.

Instance — the point of convergence: it references its customer, its License, and its license period (startLicenseDate, endLicenseDate). Everything an instance is entitled to is read through this reference — changing the License an instance runs under changes every grant it sees at once.

Entitlement usage — one record per NUMBER entitlement per instance: the running total, the number of reports that produced it, and the current period when the entitlement resets. Each report is compared with the grant of the instance's License at that moment; Usage & Metering covers what happens at the cap.

How it works

1. Define entitlements — the typed rights in your catalog, shared by every tier: POST /entitlements.
2. Create Licenses — one family per tier you sell: POST /licenses with a type opens a family, and the same call with a familySlug adds each later version to it.
3. Grant values — attach each entitlement to each License with the value that tier gives: POST /licenses/{slug}/entitlements.
4. Attach instances — every instance is created under one License version: POST /instances with the licenseId of the version its family serves, read from GET /license-families/{familySlug}.
5. Let the model work — usage reports are enforced against the grant, feature flags read it through the __kaiten facts, and every change and evaluation lands in the audit trail.

What arrives next

Coming soon

Licenses and grants are the model in production today. The commercial layer on top of them — prices, add-ons, vouchers — is on the roadmap and has no API surface yet: What's coming describes it, the editions matrix shows where each capability lands, and the vocabulary names the terms in advance.

In this section

API endpoints overview

Scopes follow the module: read:licenses / write:licenses for Licenses and their grants; reading an instance's usage needs read:instances, reporting it write:instances. See scopes.

Licenses

License families

A family has no write endpoint: its first version opens it, and deleting its last version deletes it.

License entitlements — the grants

The contract, read from an instance

Events

The six License events carry the License, the three License family events the family with the version it serves; a family event is recorded by the version write that caused it. The event catalog lists every event with its payload; events and webhooks explains the two delivery paths.

Where to go next

The one-screen version of this chain is the concept page Licenses & Entitlements; the observed side is Usage & Metering. Exact reference — tables, columns, constraints: the contract section of the data model.