Skip to content

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 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_percent from 0 to 100. Usage may go that far over the limit before access stops. grace_percent: 0 is 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 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.

POST /v1/usage
Idempotency-Key: 6c8e0a0e-…
{"customer_id": "cus_test_0001", "feature_key": "api_calls", "quantity": 1}
  • It needs a full-scope key.
  • quantity is 1 to 2^53−1, default 1.
  • Send an Idempotency-Key so 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).

{
"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".

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.