Billing

The Billing resource represents what gavAI charges you, the workspace owner, for using the platform. Use it to inspect your plan and usage, retrieve invoices, swap plans, and update your payment method on file. By the end of this page you will know which endpoints exist and the rules around plan changes and payment-method updates.

​

A billing state in shape

payment_method is null if no method is on file. Subscription status values include active, past_due, and canceled. A workspace that hits past_due enters a grace window before it moves to canceled. During the grace window the workspace stays serviceable but writes flagged as billable trigger an in-band reminder banner; once the grace window elapses without a successful retry, the workspace transitions to canceled and runtime traffic is paused. The transition is one-way through the API surface — re-enabling a canceled workspace requires resolving the unpaid invoice from the console.

​

Endpoints

Current billing state for the workspace. Change the workspace plan. Usage metrics for the current or a past billing period. Paginated list of invoices. Update the payment method on file.

​

Plan changes

POST /billing/plan takes { "plan_id": "..." }. Changes take effect at the next billing period boundary unless the platform upgrades immediately (behaviour depends on plan configuration).

​

Usage and invoices

GET /billing/usage returns a line_items array of { metric, quantity, unit } records — requests, storage, runtime_time, and similar. Omit query parameters to read the current billing period; pass period_start and period_end to read a historical window. Within an open period the numbers are running totals, refreshed in near-real-time from the runtime as events arrive. At the period boundary they freeze: the platform runs a close job that reconciles the running totals against the authoritative usage events, writes the final values, and then opens the next period. A request made during the brief close window may see slightly older numbers until the new period publishes — the response is still consistent, just not yet bumped to the new period. Plan-level usage caps (when configured) are tracked per metric. The platform reconciles each cap against actual usage on the period boundary; an overage line item appears on the invoice for the closed period if usage exceeded the cap. GET /billing/invoices is cursor-paginated. Each invoice carries id, period_start, period_end, amount, currency (ISO 4217), status (one of draft, open, paid, void, uncollectible), and pdf_url.

​

Payment method

POST /billing/payment-method accepts { "token": "tok_..." }. The typical flow is to tokenise card details client-side with Stripe.js and POST the resulting token here so raw card numbers never touch your server.

​

Common errors

​

Related