Metered usage
A metered feature is an allowance per usage period: 10,000 API calls a month, 500 exports a billing period. Your code records usage, and evaluation decides from it.
The limit and the grace margin
Section titled “The limit and the grace margin”- The limit comes from the usual order: an override, the plan version, or the feature’s default. It’s an integer or
"unlimited". - The feature has a
grace_percentfrom 0 to 100. Usage may go that far over the limit before access stops.grace_percent: 0is a hard limit.
With limit n and grace g:
| Usage this period | granted |
reason |
|---|---|---|
| unlimited limit | true |
usage_within_limit |
below n |
true |
usage_within_limit |
at or over n, below n × (1 + g/100) |
true |
usage_within_grace |
at or past n × (1 + g/100) |
false |
usage_limit_exceeded |
A limit of 0 is never granted.
The period
Section titled “The period”The period is the subscription’s billing period when both current_period_start and current_period_end are set. Otherwise it’s the UTC calendar month. Usage starts again at zero in each new period, and valid_until includes the period’s end.
Recording usage
Section titled “Recording usage”POST /v1/usageIdempotency-Key: 6c8e0a0e-…
{"customer_id": "cus_test_0001", "feature_key": "api_calls", "quantity": 1}- It needs a full-scope key.
quantityis 1 to 2^53−1, default 1.- Send an
Idempotency-Keyso a retried request isn’t counted twice. The SDKs do this for you. - The response returns the new total for the period.
In the SDKs: client.RecordUsage(ctx, "cus_test_0001", "api_calls", 1) (Go) or seal0.recordUsage("cus_test_0001", "api_calls", 1) (TypeScript).
In the evaluation result
Section titled “In the evaluation result”{ "feature_key": "api_calls", "feature_type": "metered", "granted": true, "value": 1000, "source": "plan", "reason": "usage_within_grace", "valid_until": "2026-12-01T00:00:00Z", "usage": { "used": 1100, "limit": 1000, "remaining": 0, "over_limit": true, "period_start": "2026-11-01T00:00:00Z", "period_end": "2026-12-01T00:00:00Z" }}With an unlimited value, limit and remaining are "unlimited".
Check, then record
Section titled “Check, then record”Evaluation reads usage; it doesn’t consume it. A typical flow is: evaluate, do the work if granted, then record the usage. Two requests at the same moment can both pass the check, so the grace margin also absorbs that small overshoot.