# Usage and billing

> Add credits, redeem a code, cap spending with Budgets, and see exactly what every run cost.

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

Nodus is prepaid: you add credits, and every run reserves funds before it starts. New orgs get [starter credit](https://nodus-platform-site.pages.dev/docs/guides/billing/credits/) to try things out. This guide covers the everyday tasks; the [billing concept page](https://nodus-platform-site.pages.dev/docs/concepts/billing/) explains holds, captures and limits.

## Check your balance

Terminal window

```console
$ nodus billing
Available     $17.42   purchased $15.80 · credits $3.52 (starter, expires Oct 31)
Reserved       $1.90   job/train-a, sandbox/sb-3, function/embed
This month   $232.58   budget research-monthly 42 % of $500.00
Auto-recharge  on      add $50.00 below $10.00 · visa •••• 4242
```

In the console, open **Usage & billing**. The header shows your available balance everywhere, in amber when it is low.

## Add credits

Terminal window

```console
$ nodus billing top-up 20
Opening https://checkout.stripe.com/c/pay/cs_live_... (expires in 60 min)
Waiting for payment... added $20.00. Available $37.42.
Receipt: https://invoice.stripe.com/i/...
```

Top-ups are between $5.00 and $1,000.00 in whole cents, up to $5,000 per org per day. Payment happens on a Stripe-hosted page; Nodus never sees your card number. In the console, **Add credits** offers $10, $20, $50, $100 or a custom amount and brings you back to Billing when the payment completes. A top-up settles any unpaid charges first. Every top-up has a receipt and an invoice PDF under **Receipts & invoices** and in `nodus billing receipts`.

Topping up needs the `billing:write` permission, which org Owners and Admins have.

## Auto-recharge

Auto-recharge adds credit when your available balance drops below a threshold, so long runs never stop for money:

Terminal window

```console
$ nodus billing auto-recharge --threshold 10 --amount 50
```

The first time, this opens a card setup page. Each recharge is a Stripe invoice with its own receipt. At most 5 recharges or $5,000 run per day, and three failed charges in a row turn auto-recharge off and email you. Turn it off with `nodus billing auto-recharge --off`.

**Save** updates the amounts and warning level without turning auto-recharge on or off. Use **Turn on** or **Turn off** to change that setting. If another admin or failed payments change it while you edit, the console refreshes the settings and asks you to review them before saving again.

## Redeem a promo code

Terminal window

```console
$ nodus billing redeem LAUNCH25
Redeemed ****CH25: $25.00 of credit, expires 2026-11-30.
```

See [Promo codes](https://nodus-platform-site.pages.dev/docs/guides/billing/promo-codes/) for limits and errors.

## See what you spent

Terminal window

```console
$ nodus get usage --group-by project,label:owner --since 30d
PROJECT    OWNER  AMOUNT
research   ml     $212.41
default    -      $20.17

$ nodus get usage --group-by project,meter --since 30d -o csv > usage.csv
$ nodus get transactions --since 7d
```

Group usage by `project`, `kind`, `label:<key>`, `meter`, `day`, `segment` or `rank`. `segment` splits machine time into `Boot`, `Restore`, `Running` and `Teardown`, and `rank` itemizes the members of a multi-node run. The console **Usage** tab shows the same data as a daily chart and a table, and every table exports CSV.

Transactions list every change to your balance, with the balance after it: top-ups, grants, captures, storage, egress, refunds and adjustments. [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.

## Cap spending with a Budget

A Budget is an enforced limit over the org, a project or a label selector, per month or in total. When a `Block` Budget is exhausted, work in its scope stops gracefully and new work is refused until the next period:

budget.yaml

```yaml
apiVersion: nodus.dev/v1
kind: Budget
metadata:
  name: examples-billing-monthly
spec:
  limitUSD: "25.00"
  period: Monthly
  scope:
    project: examples
  action: Block
  thresholds: [50, 80, 100]
```

Terminal window

```console
$ nodus apply -f budget.yaml
$ nodus get budgets
```

You get an email at each threshold. The console **Budgets** tab creates and edits Budgets and previews which objects a scope matches now.

To cap one person, scope a Budget to them by email. It counts everything they start, with any of their API keys, including inference requests:

Terminal window

```console
$ nodus create budget ada-monthly --limit 300 --period Monthly --scope-member ada@example.com
```

## When work is refused for money

A create that cannot be funded fails with `402` and the exact amounts, and the console shows an **Add credits** action:

|Error|What to do|
|-|-|
|`InsufficientCredits`|Add credits, or lower `spec.maxCostUSD`|
|`BudgetExceeded`|Raise the Budget’s `spec.limitUSD`, or wait for its next period|
|`ArrearsOutstanding`|Add credits; the top-up settles the unpaid charges first|
|`PaymentDisputed`|Contact support; new work waits until the dispute closes|

## Payment methods and billing details

`nodus billing portal` opens the Stripe Customer Portal, where you update cards, your billing email, address and tax ID, and download past invoices.

## Learn more

* [Credits](https://nodus-platform-site.pages.dev/docs/guides/billing/credits/): the starter credit, grants and expiry
* [Promo codes](https://nodus-platform-site.pages.dev/docs/guides/billing/promo-codes/)
* [Refunds](https://nodus-platform-site.pages.dev/docs/guides/billing/refunds/)
* [What you pay for](https://nodus-platform-site.pages.dev/docs/guides/billing/what-you-pay-for/)