# How billing works

> Prepaid credits, holds before every paid action, exact per-second charges, and what happens when money runs out.

Source: https://nodus-platform-site.pages.dev/docs/concepts/billing/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

Nodus is prepaid. You add credits, every paid action reserves funds before it starts, and charges come from the rate frozen when the capacity was acquired. Work never runs on credit you do not have, and it stops gracefully, with its progress saved, when money runs out.

## Your balance

Your org has one balance, made of buckets:

* **Purchased credit** from top-ups you pay for by card.
* **Credit grants**: the starter credit, promo codes and credits from Nodus support. Each grant is its own bucket and may expire.

Charges draw from grants first, soonest expiry first, then from grants that never expire, then from purchased credit. That way a grant is used before it expires, and purchased credit, the only kind that can be refunded, lasts longest.

`nodus billing` and **Usage & billing → Overview** show:

|Field|Meaning|
|-|-|
|Available|What you can spend now: your buckets minus open holds|
|Reserved|Open holds, with the objects that hold them|
|Purchased, credits|What is left in each kind of bucket, and the next grant to expire|
|Arrears|Unpaid charges; new work waits until a top-up settles them|

## Holds and captures

Before a Job, Sandbox, Workspace, Function worker, agent run or build starts, Nodus places a **hold**: enough funds for the first stretch of work plus the cost of stopping it cleanly. While the work runs, Nodus captures what it used every 5 minutes and renews the hold for the next stretch. When the work ends, the final capture charges the exact amount and the rest of the hold is released.

The estimate before launch shows the hold, the expected cost range and the minimum charge. A create that cannot be funded fails at once with the amounts, instead of queuing and failing later:

```text
Error from server (InsufficientCredits): job "train-a" needs a $3.20 hold to start (released when it ends); available $1.10.
  fix: nodus billing top-up 20, or lower spec.maxCostUSD
```

## What is charged

Machines Nodus acquires for you are charged per second from the moment the provider starts billing until the machine is confirmed deleted, at the rate frozen when it was acquired. Usage itemizes each machine’s time by segment (`Boot`, `Restore`, `Running`, `Teardown`). [What you pay for](https://nodus-platform-site.pages.dev/docs/guides/billing/what-you-pay-for/) lists every kind of time and who pays for it, and [Pricing](https://nodus-platform-site.pages.dev/docs/concepts/pricing/) explains how rates are set.

## Limits

Three limits apply to every hold, and the tightest wins:

* **Your balance.** A hold never exceeds what is available.
* **Budgets.** A `Block` Budget over the org, a project or a label selector stops new holds and renewals in its scope when it is exhausted.
* **Object caps.** `spec.maxCostUSD` on an object bounds that object and everything it owns.

When a limit is reached, running work stops gracefully: Jobs suspend after a checkpoint, Sandboxes and Workspaces stop, and agent runs wait. Each stopped object shows `Funded=False` with the reason, and resumes when funds return. If a charge would still go past the limit, Nodus absorbs the difference.

## Low balance

You get a low-balance warning by email, webhook and a console banner when your available balance falls below $5.00 (configurable) or below what your open holds need for their next renewal. Turn on [auto-recharge](https://nodus-platform-site.pages.dev/docs/guides/billing/#auto-recharge) to top up automatically below a threshold.

## Arrears

A charge that arrives after its hold is gone, such as daily storage, can leave unpaid charges. While arrears are open, new holds and uploads are refused with `402 ArrearsOutstanding`; your next top-up or grant settles them first.