Every capability has an overage policy. It decides what happens when a buyer organization has used up the allowance its plan grants for the current period: whether a call beyond it can be paid for from the organization's wallet, and whether earlier usage left unpaid stops further writes.
The three policies
| Policy | Value | Beyond the allowance | Usage of the period left unpaid |
|---|---|---|---|
| Block | BLOCK | Refused with quota_exhausted, unless the overage has a price and the organization's wallet balance covers the cost | Refuses every write of the capability, even within the allowance |
| Prompt to upgrade | PROMPT_UPGRADE | The same as Block | The same as Block |
| Allow and bill | ALLOW_AND_BILL | Allowed when the overage has a price and the wallet balance covers the cost; otherwise refused with quota_exhausted | Does not refuse further writes |
A call allowed beyond the allowance has remaining at 0. The cost is taken from the wallet when the usage is reported, not when the ruling is made.
Prompt to upgrade rules exactly as Block does. The name records what you intend your application to do with the refusal: show the end user a way to a larger plan. Show it in your frontend has an example.
Who rules beyond the allowance
Whether an overage can be paid for depends on the wallet, which only your application's region holds. In the Server SDK 0.1.0-beta.1, beyond the allowance, adjudicate() refuses with quota_exhausted whatever the policy; adjudicateAsync() asks the region in that case, and the region rules by the policy as above. The NestJS capability guard uses adjudicateAsync().
With Block and Prompt to upgrade, the region also refuses a write with quota_exhausted, even within the allowance, while usage of the capability in the current period has been left unpaid; this stops once credits are next added to the wallet, for example by a top-up or an adjustment.
The overage price
A call beyond the allowance can only be paid for if the overage has a price. The price is set in two places and fixed when a plan version is published:
| Where | Field | What it is |
|---|---|---|
| Capability | base_unit_price | The price of one unit beyond the allowance, in the wallet's credits. Defaults to 0 |
| Plan version | overage_discount | A multiplier between 0 and 1 applied to base_unit_price for the subscribers of this version. A new plan starts at 1; a new version copies it from the latest one |
When you publish a version, each of its entitlement rules gets an overage price of base_unit_price × overage_discount, rounded to six decimal places. Changing base_unit_price later does not change the prices of versions already published. A buyer organization pays the price of the version it subscribes to.
An overage price of 0 means the overage is not for sale, whatever the policy: calls beyond the allowance are refused, and usage reported beyond it is left unpaid.
Set the policy and the price
The policy and base_unit_price belong to the capability. Set them when you define it, with the Management API and an operator session:
POST /mgt/v1/projects/{projectId}/capabilities
Authorization: Bearer <operator session token>
Content-Type: application/json
{
"key": "report_exports",
"name": "Report exports",
"type": "COUNT",
"overage_policy": "ALLOW_AND_BILL",
"base_unit_price": 5
}overage_policy defaults to BLOCK. Change either field later with PATCH /mgt/v1/projects/{projectId}/capabilities/{capabilityId}. Set overage_discount on a draft plan version with PATCH /mgt/v1/projects/{projectId}/plans/{planId}/versions/{version}, before you publish it; published versions cannot be changed.
The full list of catalog endpoints is in the Management API reference.
When a change of policy takes effect
The region rules from each buyer organization's entitlement snapshot, which takes the capability's policy when it is built from the organization's subscription, for example when the organization subscribes or changes plan. Changing the policy of a capability does not rewrite snapshots already built, and the reset of an allowance at the start of a period keeps the policy the snapshot already has. Decide the policy before buyer organizations subscribe to plans that grant the capability.
Usage beyond the allowance is still counted
Rulings decide whether your code does the work; they do not limit what you report. Every usage event you report is counted, and the region settles its quantity in this order:
- The allowance. As much of the quantity as the allowance of the current period still covers.
- The wallet. The rest is overage. If it has a price and the wallet balance can pay the whole cost, the cost is taken from the wallet. The overage of one event is paid in full or not at all.
- Left unpaid. Otherwise the overage stays on the event as unpaid. It is never charged afterwards. Under Block and Prompt to upgrade, it refuses further writes of the capability until credits are next added to the wallet, as described above.
Because two requests ruled at the same moment can both be allowed, usage can go beyond the allowance even under Block. Where that must not happen, reserve the amount before the work instead; see A ruling holds nothing.
End users top up their wallet themselves; see the Public API. You can credit or debit a wallet by hand with POST /mgt/v1/projects/{projectId}/wallets/{orgId}/adjustments.