Usage & Metering

Usage is what an instance has consumed of a NUMBER entitlement. Kaiten keeps one record per entitlement per instance — a running total plus the number of reports that produced it — and compares it against the grant of the instance's License every time your product reports. The grant is the contract; usage is the observation; the comparison is where enforcement happens.

Reporting

Your product's backend reports with POST /instances/{slug}/entitlements/{slug}/usage, carrying a number and a behavior. append folds the value into the stored total through the entitlement's aggregation method — SUM for counters like monthly-orders, LATEST for gauges like menu-items and delivery-drivers where each report states the current count, MAX for peaks, COUNT, AVERAGE, MIN. set overwrites the total with an absolute value, which is how you correct a counter downward. Reading back (GET on the same path, or …/entitlements/usage for every entitlement at once) returns the current value, the limit the License grants, and the bounds of the current period.

Reporting a BOOLEAN or CONFIG entitlement is refused — there is nothing to count. Their value is read, not metered.

Two numbers on the grant decide

Enforcement is derived from two numbers on the grant, and nothing about it sits on the entitlement. The two numbers are the value a License gives and limitCapExceededOveragePercent, how far past that value a report may go:

One comparison, on every report: a total that would land above the maximum allowed usage is refused with 409 and not written — the stored total does not move, and the refusal is recorded as ENTITLEMENT_USAGE_REPORT_REJECTED. Anything up to the maximum is accepted, overage included.

Because the numbers live on the grant, the same entitlement is enforced differently per License: Ninja Osaka's Starter instance holds menu-items at 5 of 5 on a hard cap, so its next report is refused; Demo Restaurant, at 6 of 10 with Standard's 10 % allowance, can report 11 — accepted, one past the value — but not 12; Premium's locations is unlimited while Starter's is a hard cap of 1. NUMBER_AI_CREDIT follows exactly the same rules as NUMBER.

Three signals mark the way up: a total that lands exactly on the value fires INSTANCE_ENTITLEMENT_USAGE_REACHED; crossing the value inside the allowance fires INSTANCE_ENTITLEMENT_CAP_EXCEEDED, once per crossing; crossing the entitlement's warning threshold — warningThresholdPercent of the value, the one threshold that stays on the catalog, off at 0 — fires INSTANCE_ENTITLEMENT_USAGE_WARNING_THRESHOLD_REACHED, once per crossing. Kaiten enforces at the report boundary; what a refusal means for the end user — a disabled button, an upgrade prompt — is your product's decision.

Periodic counters

By default a counter is for the lifetime of the instance. An entitlement can instead declare a reset period — HOUR, DAY, WEEK, MONTH, YEAR — and an anchor: CALENDAR aligns windows to the UTC calendar, LICENSE_START phases them off the instance's startLicenseDate. monthly-orders is monthly and calendar-aligned. The rollover is evaluated lazily: a read after a window closes already shows the new window at zero, and the next report rolls the counter over and records each closed window as INSTANCE_ENTITLEMENT_USAGE_PERIOD_ROLLED_OVER — including empty intermediate windows when an instance was silent for a while, so the history has no gaps. The response fields currentPeriodStart and currentPeriodEnd show the window a total belongs to; for a lifetime counter they are omitted.

Every read and report is recorded

Reading a single entitlement's usage emits ENTITLEMENT_VALUE_GET; each report emits its acceptance or refusal; every crossing and every closed window is an event. All of them land in the instance's audit trail — the line-by-line receipt a customer can be shown when usage is disputed.

Where to go next

Meter usage and enforce limits walks three seeded instances to a hard cap, into an allowance, and past an unlimited grant. In depth, in the Entitlements deep-dive: the window mechanics under metering, the allowance arithmetic under usage and thresholds.

Exact reference: data model.