| name | billing-lib |
| description | Use when writing or reviewing code that meters API token usage, bills accounts, issues invoices, applies credit grants, or computes balances with the internal `billing` library — especially around retries, mid-cycle plan changes, cache-read vs cache-write token pricing, or any place where double-billing or rounding drift would be a problem. |
billing-lib
Overview
billing is the internal usage-metering and invoicing library. It records token consumption per account, prices it against the active plan, and rolls events into invoices, credit grants, and balances. Every metering and money path is idempotent and integer-cent based — getting either wrong silently corrupts customer bills.
When to Use
Use this skill when you are:
- Recording token usage for a request (
meter_usage) from an inference service or gateway.
- Pricing cache-read vs cache-write vs base input tokens differently.
- Generating invoices, applying credit grants, or reading account balances.
- Handling retries / at-least-once delivery where the same usage event may arrive twice.
- Changing a plan mid-cycle and needing correct proration.
- Reconciling a balance that "looks off" by a few cents.
Do NOT use this for: public-facing pricing display logic, the marketing pricing page, or the Stripe/processor integration layer (that lives in payments, not billing). This library stops at producing the invoice; it does not charge cards.
Core Model
- All money is stored as integer cents (
int), never floats. A Money type wraps cents; never construct prices from float.
- Token quantities are
int. Pricing is cents_per_million_tokens (an int), so cost = with explicit rounding (see Gotchas).
