Usage & entitlements

Record usage via HTTP or StatsD. Check feature access and consumption warnings before gated actions.

Usage classification

When a subscribed user records usage, the plan may reroute or reject the event before it is stored. Processing order: JSON classify.routes → JSON classify.reject → limits[] → Luau classify (if defined). Routes can filter by time, calendar, event quantity, period usage, and source — see Plan extensions → JSON classify and Luau classify examples.

Entitlements

Features are defined in the catalog, then attached to plans with optional effective_from. Check access with POST /entitlements/check — pass at to inspect historical state.

Consumption flags

Derived usage warnings for a user, separate from feature entitlements. Query GET /consumption-flags?user_id=… with optional at for historical state.

Flag	Meaning
`usage.near_limit`	Per metric or metric group — at or above 80% of included
`usage.over_limit`	Per metric or metric group — above included quota
`usage.current_tier`	Per metric with graduated tiers

Metrics in a metric_groups entry or usage_pool do not emit per-metric near/over flags; the group aggregate is checked instead.

Dual ingestion

Use HTTP for domain events and catalog operations. Use StatsD UDP for high-frequency per-click metering.

text

billing.<tenant_id>.<api_key>.user.<user_id>.<metric_code>:<value>|c

Optional idempotency: |#event_id:evt-123. |g gauge type is accepted but treated as usage quantity. Full packet format: HTTP API → StatsD.