# Billing & credits

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](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)

1. Human adds a card via SetupIntent (`ozma billing setup`) or Billing Portal (`ozma billing portal`).
2. Org flips to `billing_mode = postpaid`.
3. After credits exhaust, successful calls enqueue Stripe meter events.
4. Stripe invoices on the subscription cycle.
5. [Spend governance](/docs/guides/keys-and-budgets) still applies on every call.

```bash
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 | — |

```bash
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):

```bash
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 |

## Related

- [Pricing & payouts](/docs/guides/pricing-payouts)
- [Keys & budgets](/docs/guides/keys-and-budgets)
- [Troubleshooting](/docs/guides/troubleshooting)