Credits
A credit is a prepaid wallet unit. 100 credits = 1 USD cent.
Credits are never a count of activity. Usage rates in the console and customer UI are money per meter noun (
$0.02 / request). Credits stay on the balance widget and ledger.
Meter noun
A meter defines what to count. Every provider is seeded with one meter:
MCP tool calls also record usage under
tool:{toolName} meter names. Custom meters may use another noun (documents, tokens). Copy uses that noun: “1,000 requests included”, not “1,000 units”.
A usage event is one recorded data point against a meter. The HTTP path stays POST /v1/sdk/meter-events.
Included vs remaining
Two leftover counts exist. Do not mix them.
When a request names a
free-* meter (CheckLimitRequest.freeAllowance), remaining is the free-allowance remainder, not included remaining. The field is reused; the meter name tells you which count it is.
The stored included cap is LimitOption.cap. Copy says included, not “limit” or “quota”. A free allowance is the code-declared cap on registerFree (FreeLimit.cap). Do not call a free allowance included.
Recurring, usage-based, hybrid, and one-time are derived labels from options[], not stored plan types. See Plans.
LimitOption.cap === 0 means unlimited. Commerce emits that sentinel on the wire as freeUnits: 0. A missing limit option is pay-as-you-go (no included amount), not unlimited.
Overage
Overage is usage beyond the included allowance, charged per meter noun and paid from prepaid credits. A plan with no included cap pays for every counted item from credits at the per-request rate.Activation and paywall
POST /v1/sdk/activate follows the plan shape:
A usage plan’s empty wallet surfaces later as
topup_required at usage time, not at activation.
paywallReason on a limits denial names the recovery. limit_reached is also how a registerFree allowance reports exhaustion.
See Add a free allowance to MCP tools.
Credit minting
Credits mint when the charge succeeds. The webhook is an idempotent backstop, not the primary booking path.Words to avoid
Wire identifiers (
units, CHARGE_PERS = 'unit', customer.credit.auto_topup_failed) stay as published.
Next steps
- Plans — plan types and configuration
- Billing — cycles, renewals, and usage on a purchase
- Usage events — record usage from the TypeScript SDK
- Add a free allowance to MCP tools — code-declared per-customer cap