Checkout & invoices

Top up your credit balance with a card via Stripe Checkout. Every top-up produces an invoice.

How top-ups work

You request a top-up amount.
Cloud API opens an invoice (status open) and a Stripe Checkout session.
You pay on Stripe's hosted page and return to the dashboard.
Stripe's webhook credits your balance (plus any configured bonus) and marks the invoice paid.

Start a checkout

bash
POST /v1/billing/checkout
{ "amountCents": 2500 }
→ { "url": "https://checkout.stripe.com/...", "invoiceNumber": "INV-2026-000042" }

Redirect the user to url. The minimum amount and any bonus percentage come from GET /v1/billing/config.

Invoices

bash
GET /v1/invoices            # your invoices
GET /v1/invoices/:id        # one invoice with line items

Invoices have a sequential human-readable number (e.g. INV-2026-000042), a status (open, paid, void), line items and totals. The dashboard can render a printable copy. Both endpoints require the billing:read scope; starting a checkout requires billing:write.

Bonus credit

Admins can configure a top-up bonus (e.g. +10%). When set, paying $25 might credit $27.50 — the bonus is shown at checkout and recorded as a line item on the invoice.

See also Credits & billing for how usage is metered.