> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Billing

> Credit, the reservation rule, budgets, cards and invoices.

### The reservation rule

Creating work reserves its worst case, which is its `timeoutMs` at \$1.10/h, from creation until it ends. The plane admits new work only if that worst case fits:

| Work | Reserves |
| - | - |
| A sandbox with the default 15-minute timeout | \$0.275 |
| A task with the default 30-minute timeout | \$0.55 |
| A 1-hour sandbox | \$1.10 |
| A 24-hour sandbox | \$26.40, more than the free credit |

* **Work is prepaid**, with or without a saved card. Every reservation together must fit in the remaining credit, including signup, purchased and operator-granted credit. Otherwise the answer is 402 `payment-method-required`. Saving a card alone does not fund work. Buy credit or enable auto-reload in the console under Billing.
* **With an enforced monthly budget**, this month's spend beyond the credit, plus every reservation the remaining credit does not cover, must fit under the budget. Credit never counts against a budget, so a team with granted credit is not stopped at the default \$50. Otherwise the answer is 402 `budget-exceeded`.

Because running work can never spend more than its reservation, an enforced budget is never exceeded, and nothing is killed mid-run to keep that promise. Ask for the `timeoutMs` you need, not the maximum. Lengthening a sandbox's timeout reserves the difference.

### Budgets and invoices

* A new team starts with a monthly budget of \$50, enforced. The owner changes it in the console (`PUT /v1/billing/budget` with `{"limitUsd": number | null, "enforce": boolean}`, session only, owners only).
* Alerts fire once a month at 50%, 80% and 100% of the budget.
* Credit is consumed as work runs; there is no monthly usage charge beyond it. Owners buy credit or enable auto-reload in the console.
* An amount under Stripe's \$0.50 minimum is carried to the next month, as status `deferred`.

### Billing calls

Saving a card alone does not add prepaid credit. On a deployment with `mode: "off"`, payment-changing calls answer 409 `billing-unavailable`.

| Call | Credential | Answer |
| - | - | - |
| `GET /v1/billing` | key or session | The billing object below |
| `GET /v1/billing/invoices` | key or session | `{"invoices": [{"id", "number", "period", "createdAt", "subtotalUsd", "creditUsd", "carriedUsd", "totalUsd", "status", "hostedUrl", "failureMessage"?, "lines": [{"description", "amountUsd"}]}]}`, newest first. `status` is `paid`, `open`, `failed` or `deferred`; `carriedUsd` is what came over from earlier months, and `failureMessage` says why a `failed` charge was declined |
| `PUT /v1/billing/budget` | owner session | The billing object |
| `POST /v1/billing/checkout` `{returnUrl}` | owner session | `{"url"}`: send the browser there to add a card |
| `POST /v1/billing/checkout/complete` `{sessionId}` | owner session | The billing object, with the card attached |
| `DELETE /v1/billing/card` | owner session | The billing object, with the card removed |
| `POST /v1/billing/portal` `{returnUrl}` | owner session | `{"url"}` to the payment provider's customer portal (409 `no-portal` in test mode) |

```json theme={null}
{
  "mode": "off",
  "plan": { "id": "payg", "name": "Pay as you go", "usdPerHour": 1.1 },
  "card": null,
  "postpaid": false,
  "credit": { "grantedUsd": 5, "usedUsd": 1.2, "remainingUsd": 3.8 },
  "period": { "id": "2026-10", "start": 1790812800000, "end": 1793491200000, "spentUsd": 1.2, "reservedUsd": 0.25, "estimatedInvoiceUsd": 0 },
  "budget": { "limitUsd": 50, "enforce": true, "alertThresholds": [50, 80, 100], "alerts": [] },
  "ceiling": { "limitUsd": 100, "usedUsd": 0, "remainingUsd": 100 },
  "status": "active",
  "portal": false
}
```

* `mode` is `live` (real cards through Stripe), `test` (the test checkout or a Stripe test key: no real money moves) or `off` (card payments are not open yet: work is limited to available granted credit, and `POST /v1/billing/checkout` answers 409 `billing-unavailable`).
* `card` is `null` until a card is added.
* `status` is `active` or `past_due`. A `past_due` object also has `failureMessage`.
* `reservedUsd` is what in-flight work holds beyond what it has already used.
* `postpaid` and `ceiling` are set only for a few accounts billed monthly by arrangement. Other teams can ignore them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.