# Billing

You are billed **the clearing price for capacity you hold** —
never above your declared ceiling, and usually below it (during a
[minimum-duration protection window](https://docs.nationalcompute.com/market.md#minimum-duration-protection)
the assessed rate can be as high as your ceiling). Billing rides prepaid
credits managed on the console's **Billing** page, where self-serve
purchases are available.

## Buying credits

Credits are prepaid at **$1 = 1 credit**, topped up from the Billing
page in one of two ways:

- **Credit card ($50,000 per 7 days)** — self-serve, through a
  Stripe-hosted checkout (card details never touch the console). Your
  organization's card payments may total $50,000 inside any rolling 7
  days. Every card payment counts, one time top ups and auto reload
  charges alike. The Billing page shows what a card can still carry
  right now. The cap frees up as payments older than 7 days age out.
- **Wire transfer** — for payments above $50,000 and for anything
  beyond the 7 day card cap. The receiving-bank
  and beneficiary details and your organization's wire reference are on
  the console's Billing page under **Wire transfer**, and on the billing
  API's summary as [`wire`](https://docs.nationalcompute.com/api/billing.md#wire-transfer) for an agent.
  You **must**
  include the reference in the wire's memo field — it identifies your
  organization and ensures your account is credited promptly. Email
  [billing@nationalcompute.com](mailto:billing@nationalcompute.com)
  when you send a wire so we can keep an eye out for it.

## What the meter measures

For burst capacity the market's own record is the bill: every auction
tick records the rate assessed to each winning unit, and charges are
accounted at those market-run boundaries — when a node arrives, when
its price changes, when it leaves. A [base load block](https://docs.nationalcompute.com/market.md#base-load-capacity)
is the exception and has its own section below.

- **VM clusters** — a node bills from grant completion to the start of
  reclaim. You pay while you hold it, whether or not jobs are running;
  holding is under your control (`max_gpus`, `release`, swap).
- **Kubernetes clusters** — a node bills while it is a joined member
  serving your cluster, with a minimum of one hour per granted node:
  the [minimum hold](https://docs.nationalcompute.com/market.md#minimum-duration-protection) keeps the
  node yours for its first hour even if its job finishes sooner. After
  the first hour, charges accrue in minimum increments of five
  minutes, and because [nodes join when jobs need them and shed when
  idle](https://docs.nationalcompute.com/kubernetes.md), billing tracks actual use without any action
  from you.

## Base Load Capacity

A [base load block](https://docs.nationalcompute.com/market.md#base-load-capacity) bills its **fixed rate for
every node in the block across the whole term**, idle or busy,
delivered or being replaced — that is what the fixed rate buys. Charges
land on your credit balance in the same five-minute cadence as burst
capacity; each charge names the block it belongs to. The block's
nodes never appear in the market's clearing rates, and burst nodes you
hold beyond the block bill as ordinary burst capacity. Billing
stops at the end of the term, or at the moment a block is
cancelled by a billing hold reaching enforcement.

## Marshall model usage

Marshall's model calls are metered per member and charged to your
organization's credits from the first call, in the same credit
unit as capacity, about every five minutes, as one ledger row per
organization naming the members and the amount each used. The charge
counts toward your [monthly spend limit](https://docs.nationalcompute.com/api/billing.md#balance-and-totals)
like every other charge.

When your organization's balance reaches zero (or a billing hold is
active), Marshall is paused for every member. Adding credits resumes
Marshall within a minute. Marshall is never paused while your balance
is positive, so the balance can run slightly below zero on the last few
calls.

The ledger reads these rows as source `inference`; the console's
Billing page shows them under the **Marshall** chip and as the
"Marshall model usage" series on the usage chart. The
[billing summary](https://docs.nationalcompute.com/api/billing.md#balance-and-totals) carries the
organization's charged model usage as `inference`.

## Public Research leases

A [Public Research](https://docs.nationalcompute.com/public-research.md) node bills per GPU-hour, for
every GPU in the node, at the flat rate in force when the lease was
granted, from the moment the node is yours to the moment the lease ends:
released, preempted, lost, ended at zero balance or ended by National
Compute alike. The rate
is on the Marshall quote and on the Billing page under Rates; a change
to it applies to leases granted afterwards and never reprices a running
one. Waiting in the queue and the rebuild after a lease cost nothing. A
request is admitted only with a balance covering the first hour of a
lease; a balance that reaches zero ends a running lease, and a billing
hold refuses new requests.

The ledger reads these rows as source `public_research`; the console's
Billing page shows them under the **Public Research** chip, and the
[billing summary](https://docs.nationalcompute.com/api/billing.md#balance-and-totals) carries the
month's GPU-hours and charged amount as `public_research`.

## What is never billed

- **Ticks that clear at $0.** An uncontended market can clear at a
  real $0 rate — those hours cost nothing.
- **Gaps in the market record.** If the platform's market loop has an
  outage, the gap is unbilled — the platform's loss, never yours.
- **Pending capacity.** Declared demand that hasn't been granted costs
  nothing; you pay only from the moment a node is yours.

## Reading your records

Every charge above is a ledger row your organization can read with its
API token — per node, per price window, with burst, base load and
storage told apart — through the
[billing records API](https://docs.nationalcompute.com/api/billing.md). The console's Billing page
renders the same rows.

## Predicting your spend

Read your rate instead of estimating it. `GET /api/billing/balance` on
the [billing records API](https://docs.nationalcompute.com/api/billing.md#balance-and-burn-rate) returns
your balance with the hourly rate the meter last assessed across your
organization, folded by kind, cluster and unit price, so jobs bidding
different ceilings show as separate lines, and
`GET /api/billing/balance/history` shows how the balance has moved. The
figure is 5 to 10 minutes behind the market. Your worst case is still
arithmetic: held GPUs × your declared ceiling. The
[market feed](https://docs.nationalcompute.com/api/market-feed.md) publishes what capacity really clears
at, per tick and as a long-run series, and every capacity read echoes
your own declared ceiling.

## Invoices

An organization that can pay by card can also issue itself an invoice
for prepaid credits and pay it by wire through its accounts payable
team. The platform issues, records and serves the document; nobody at
National Compute is in the loop. Request one on the portal's billing
page, under the wire transfer rail, or ask Marshall for one.

The bill-to block is the organization's **billing profile**: a name,
one to six address lines and an optional email, set once by any member
and printed on every invoice issued afterwards. Editing the profile
never rewrites an issued document.

**The invoice id is the wire memo.** Put it in the transfer's reference
or memo field. Credits land when the wire does; issuing an invoice moves
no credits. Terms are due on receipt.

The billing page lists the organization's invoices with a download for
each. An open invoice can be cancelled there (or through Marshall): it
stops being payable and no credits move. A paid invoice is never
cancelled, and a cancelled invoice is never paid.

| Limit | Value |
| --- | --- |
| Amount | any positive dollar figure, at most two decimals |
| Open invoices per organization | 10 (currently); pay or cancel one before issuing another |
| Invoices per organization | 1,000 (currently), every status counted |
| Organizations on a reserved arrangement | refused; finance invoices them under the contract |

Issuing refuses with one of these codes; the portal and Marshall name
the fix in the same answer.

| Code | Status | Meaning |
| --- | --- | --- |
| `bad-request` | 422 | a field is malformed; `field` names it |
| `profile-missing` | 409 | set the billing profile first |
| `self-serve-off` | 409 | the organization cannot pay by card (a reserved arrangement, or card purchases off) |
| `open-limit` | 409 | ten invoices are open; `open_limit` and `open_count` carry the numbers |
| `invoice-limit` | 409 | the organization holds its maximum; `invoice_limit` carries the number |
| `not-open` | 409 | a cancel of an invoice that is paid, void or already cancelled; `invoice_status` says which |

With an org API token the invoices are readable, not issuable: there is
no issue verb on the token API.

| Route | Answers |
| --- | --- |
| `GET /api/billing/invoices` | `{profile, invoices, invoice_count, invoice_limit, open_count, open_limit, self_serve}` |
| `GET /api/billing/invoices/{id}.pdf` | the document, `application/pdf` |

Each invoice carries `id`, `amount_usd`, `status` (`issued`, `paid`,
`void` or `cancelled`), `date`, `due_date`, `bill_to` as printed,
`wire_memo` (the id), `cancellable` and `pdf_path`. Another organization's id, an unknown id and a
malformed id are the same `404`. Organizations without the feature read
`404` on both routes.