API reference

Billing

The organization's plan, usage, and limits. How sandbox time is counted is on Sandbox time and plans. :id and organization_id are the organization's ID.

The account object#

Field	Meaning
`organization_id`
`plan`	`id`, `version`, `name`, `monthly_usd`, `comped`.
`subscription_status`	The subscription's status, or null.
`cancel_at`	When a cancellation at the period end takes effect, or null.
`scheduled_change`	`{ "plan_id", "at" }` for a switch held to the period end, or null.
`payment_method`	Whether a payment method is on file.
`payment_method_required`	Whether cloud runs need one.
`period`	`start`, `end` of the current allowance period.
`hours`	`used`, `included` (a number or `"unlimited"`), `remaining` (or null).
`overage`	`rate_usd_per_hour` (or null), `hours`, `usd`, `projected_hours`, `projected_usd`.
`spend_limit`	`usd` (a number or `"unlimited"`) and `source`: `override`, `organization`, or `plan`.
`members`	`used`, `limit` (a number or `"unlimited"`).
`private_workbenches`	`used`, `limit`.
`override`	Limits set by workbenches.dev for the organization, with `reason` and `expires_at`, or null.

Get the account#

GET /v1/billing/accounts/:id

Key catalog:read, or session: member. Response 200: the account.

Set the spend limit#

PATCH /v1/billing/accounts/:id with { "spend_limit_usd": 100 }

An owner or admin, by session or key. The monthly overage spend limit in dollars, at least 0. Response 200: the account.

Checkout#

POST /v1/billing/checkouts

An owner or admin, by session or key. Starts Stripe Checkout:

Body	Purpose
`{ "mode": "subscription", "organization_id", "plan_id" }`	Upgrade to a public paid plan.
`{ "mode": "setup", "organization_id" }`	Add a card.

Response 201 { "url" }: send the customer there. Checkout is refused while a subscription is live; use the portal or a plan switch instead.

Return from checkout#

POST /v1/billing/checkouts/returns with { "organization_id", "session_id": "cs_..." }

An owner or admin. Applies the Checkout session's subscription now and returns the account, so a paid organization never sees Free.

Customer portal#

POST /v1/billing/portals with { "organization_id" }

An owner or admin. Response 201 { "url" } to the Stripe customer portal: cards, invoices, and cancellation at the period end. The portal does not switch plans.

Switch plans#

Preview a switch#

POST /v1/billing/plans/previews with { "organization_id", "plan_id" }

An owner or admin. Changes and charges nothing. Response 200:

Field	Meaning
`effect`	`now` for an increase, `period_end` for a decrease.
`due_now_usd`	What is charged now.
`current_monthly_usd`, `new_monthly_usd`	Both monthly prices.
`takes_effect_at`	When the switch applies.
`next_invoice_at`
`proration_date`	Pass it to the switch, or null.

Switch#

POST /v1/billing/plans with { "organization_id", "plan_id", "proration_date" }

An owner or admin, for a paying organization. An increase applies at once and invoices the prorated difference shown by the preview; a proration_date older than 15 minutes is refused with a request to review again. A decrease is held until the period ends. Response 200: the account plus effect (now or period_end).

Plan limits#

Enforcement refuses with 402 plan_limit and a message naming the limit and the upgrade path:

POST /v1/runs without a payment method, with no sandbox time left, past the spend limit, or with a max_minutes longer than the time available.
POST /v1/invitations and POST /v1/acceptances at the member cap.
POST /v1/versions for a new Workbench at the private Workbench cap.