Billing & credits
Usage-first billing, trial credits, packs, postpaid, auto-reload, and suspension.
View as Markdown →Ozma billing is usage-first (OpenAI-style): trial credits → optional card on file → Stripe meter → invoice. Prepaid credit packs remain available for pay-in-advance workflows.
Dashboard: https://ozma.app/dashboard/billing
Trial credits
| Signup path | Credits | When granted |
|---|---|---|
Human signup (/v1/signup, /v1/auth/signup) |
$1.00 (100 cents) | After email verification (prod default) |
| OTP login first verify | 100 cents | Idempotent grant |
Agent POST /v1/register |
0 | Immediate — free APIs only |
Credits apply first on each call; only the remainder (billable_cents) meters to Stripe for postpaid orgs.
Free APIs
Catalog endpoints with price_cents = 0 never require a card and never burn credits. Platform seed APIs (e.g. Frankfurter, httpbin.org) are permanently free.
Usage / postpaid (primary)
- Human adds a card via SetupIntent (
ozma billing setup) or Billing Portal (ozma billing portal). - Org flips to
billing_mode = postpaid. - After credits exhaust, successful calls enqueue Stripe meter events.
- Stripe invoices on the subscription cycle.
- Spend governance still applies on every call.
npx @ozma_app/cli billing setup --json # client_secret — confirm in browser
npx @ozma_app/cli billing portal --json # manage cards/invoices
npx @ozma_app/cli balance --json
Human card step required: agents receive SetupIntent secrets but cannot complete 3DS/card entry without a browser (dashboard or Stripe.js).
Prepaid packs (optional)
| Pack | Price | Bonus |
|---|---|---|
starter |
$10 | — |
growth |
$25 | +$2.50 |
scale |
$100 | +$15 |
| Custom | $5–$1,000 | — |
npx @ozma_app/cli billing packs
npx @ozma_app/cli billing checkout --pack starter
Checkout requires billing:write (verified email). Completed sessions credit the org wallet idempotently.
Auto-reload
Optional wallet refill when balance drops below a threshold (requires card on file):
npx @ozma_app/cli billing auto-reload --enable --threshold 200 --amount 1000
Maps to POST /v1/billing/auto-reload. Less central under pure usage invoicing but useful for prepaid-heavy workflows.
Dunning & suspension
Postpaid orgs with invoice.payment_failed three times are suspended. Gateway returns 402 payment_required on billable calls until invoice.paid clears suspension.
Prepaid orgs with zero credits and no card hit 402 with dashboard top-up hints.
What agents can vs cannot do
| Action | Agent | Human |
|---|---|---|
| Call free APIs | Yes | Yes |
| Call paid APIs with credits/card on file | Yes | Yes |
| Add first payment method | No | Yes |
| Stripe Connect KYC (providers) | No | Yes |
| Checkout / portal | Opens URL | Completes payment |