An allowance is how much of a capability a buyer organization may use in the current period under its plan. Your application's region counts every accepted usage event against it, one event at a time. This page follows one event through that count.
Where an allowance comes from
You set allowances in your catalog. Each plan version grants capabilities through its entitlement rules, one rule per capability:
| Part of the rule | What it sets |
|---|---|
| Allowance | How much of the capability the plan includes, as a number of 0 or more. There is no unlimited allowance |
| Reset interval | MONTHLY: the allowance starts again each month. NEVER: it is never reset |
| Overage price | What one unit beyond the allowance costs: the capability's base unit price times the plan version's overage discount, fixed when the version is published. A capability without a base unit price has no overage price |
A published plan version cannot be changed, so a buyer organization's allowance changes only when you publish a new version and move the organization to it, or when the organization moves to another plan. How plans and versions are made is in Subscriptions.
When a subscription becomes active, the region gives the buyer organization one entry per capability the plan grants: the allowance, what is used so far, and the bounds of the current period. That set of entries is the organization's entitlement snapshot, the same data the Server SDK keeps in memory to rule on. A capability the plan does not grant has no entry: rulings refuse it and the region refuses its usage events.
How each event is cleared
The region clears each accepted event in its own database transaction, in this order:
- Repeats are dropped. An event whose
usage_event_idwas already accepted is not counted again. - The allowance is used first. The quantity is counted against what is left of the organization's allowance for the capability, up to the allowance.
- The rest is the overage. If the capability has an overage price and the organization's wallet covers the whole cost of the overage at that price, the cost is taken from the wallet. With the overage policy Allow and bill, the wallet may go down to any overdraft limit you set; with Block and Prompt to upgrade, only the wallet balance counts.
- Otherwise the overage is left unpaid. If the capability has no overage price, or the wallet cannot cover the whole cost, nothing is taken from the wallet. The event is still accepted and recorded, with the part that was not paid.
Usage left unpaid in the current period changes later rulings. With Block and Prompt to upgrade, the region refuses a write of the capability with quota_exhausted, even within the allowance, until credits are next added to the wallet; see When the allowance runs out.
Events for the same organization and capability that arrive at the same time are cleared one after the other, so none of them is lost or counted against the same part of the allowance twice. An event is cleared when the region receives it, against the allowance as it is at that moment; occurred_at records when the work happened.
Reservations
A reservation takes its amount from the allowance when it is made, not when it is confirmed. Confirming it gives that amount back and clears the amount actually used in the order above; releasing it gives the amount back and clears nothing.
Example
A plan grants 1,000 llm_tokens, the organization has used 900, and the capability has an overage price. A usage event of 250 tokens arrives:
- 100 tokens are counted against the allowance, which is now used up.
- The remaining 150 tokens are the overage. If the wallet covers the cost of 150 tokens, it is taken from the wallet. If it does not, nothing is taken, and the 150 tokens are left unpaid.
- Later rulings show
remainingat 0 andlimitat 1,000.
When the organization changes plan
When a buyer organization moves to another plan, each capability takes the allowance of the new plan version, and what was used so far in the period stays counted against it. Capabilities that the new plan does not grant are removed from the organization's snapshot. The region announces the change, and the Server SDK uses the new allowances in its next rulings without a restart of your process.
The period of an allowance
Each entry of the snapshot carries the bounds of its current period and its reset interval. The bounds are taken from the subscription when it becomes active or moves to another plan. The usage summary shows them as period_start, period_end and reset_interval; the Management API shows ends_at and reset_interval for every buyer organization.
Shortly after period_end of an allowance whose reset interval is MONTHLY, the region starts the next period:
- What is used goes back to 0, and the whole allowance is available again.
- The period moves on by a month, in UTC, keeping the day of the month it started on. In a shorter month it ends on the last day: a period anchored on the 31st ends on February 28 or 29, then on March 31. If more than one period has passed, the region moves straight to the one that contains the current time.
- Your backend sees the new period without a restart. The region announces the change, and the Server SDK refreshes the organization's snapshot, so the next ruling shows the full
remaining.
An allowance whose reset interval is NEVER is never reset: what is used keeps counting against it.
A reservation that is still open when its period ends does not carry its amount into the new period: if it is released or reclaimed afterwards, nothing is given back to the new period, and if it is confirmed, the amount used is counted in the period in which it is confirmed.
Amounts
Allowances, usage and quantities are decimal numbers kept to six decimal places, so a capability can be metered in fractions, such as hours of compute. The Server SDK takes and returns them as numbers; the region's APIs carry them as decimal strings.