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.
The stored included cap is
LimitOption.cap. Copy says included, not “limit” or “quota”.
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 allowance), not unlimited.
Overage
Overage is usage beyond the included allowance, charged per meter noun. A plan with no included cap is pure pay-as-you-go: every counted item is billed 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.
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