# Credits Your organization's prepaid credits ([buying credits](https://docs.nationalcompute.com/billing.md#buying-credits)) pay for each charge in a fixed order and can be owed; a billing hold stops capacity that nothing can pay for. The console's Billing page shows every figure on this page, and the [billing API](https://docs.nationalcompute.com/api/billing.md#credit-balances-and-debt) carries the same figures. ## Credit balances Your organization's credits sit in one or more **credit balances**, each of one kind: - **Standard** credits pay for anything and never expire. They are the default: a card or wire payment becomes Standard credits once it has paid any [debt](#payments). - **Restricted** credits pay only for the clusters, sites or services they [name](#restricted-credits). - **Promo** credits come from grants and always [expire](#promo-credits). A Promo balance can also be restricted. Part of a balance can be **locked** for one [Base Load](https://docs.nationalcompute.com/market.md#base-load-capacity) reservation's term. Locked credits pay only that reservation. The console's Billing page lists them under **Your credit balances**: the kind, what the balance applies to, what remains of the original amount, the part locked, and the expiry date. A balance with nothing left drops off the list 90 days after it was created. The [billing API](https://docs.nationalcompute.com/api/billing.md#credit-balances-and-debt) carries the same list as `credit_balances`. ## Total balance and available to spend **Total balance** is the Billing page's headline and the API's `balance_ucredits`: the sum of your credit balances, locked credits included, minus your [debt](#debt-and-unpaid). It goes negative when the debt is larger. **Available to spend** is what can pay for a charge in one place right now: the unlocked credits that may pay there, plus the unused room on [advances](#advances) that cover it. It is figured per scope: each of your clusters, Marshall models, the public research pool (on a public research organization), and anything else (a charge tied to no cluster or service, which only unrestricted credits pay). The Billing page shows one figure per scope under **Available to spend**. Gates and [billing holds](#billing-holds) read available to spend, less the unpaid that hits the same scope, never the total: a Restricted balance for one cluster funds only that cluster. For an organization whose money is one pool, every one of these figures equals the total balance. ## Spend order Every charge is paid by the first eligible money, in this order: 1. for a Base Load charge, the reservation's own locked credits; 2. Restricted credits that apply, narrowest first (one naming clusters, then one naming a site, then one naming only services), then soonest expiry, then oldest; 3. Promo credits with no restriction, soonest expiry first; 4. Standard credits, oldest first; 5. advances that cover the charge, a restricted advance before an organization wide one, soonest due first; 6. whatever is left becomes unpaid in the charge's own scope. The order is the platform's, and you cannot change it. National Compute can set a different order of steps 2 to 5 for an organization; the lock always comes first and unpaid always last. A metered row is split by what it paid for (each cluster's compute and storage, Marshall models, Public Research), and each part walks the order on its own. Each ledger row's `allocations` show which money paid it ([the ledger](https://docs.nationalcompute.com/api/billing.md#the-ledger)). ## Debt and unpaid **Debt** is what your organization owes: draws on [advances](#advances) plus unpaid. **Unpaid** is usage that nothing eligible could pay, kept in the scope it was used in ("Unpaid usage on acme-b"), and advance draws left owing after their grace period. Unpaid from a charge tied to no cluster or service has no scope. The Billing page lists debt under **What you owe**; the API carries `debt_ucredits`, `unpaid[]` and `advances[]`. ## Advances An **advance** is authorized debt up to a limit that National Compute opens for your organization, optionally restricted to named clusters or services and optionally tied to an invoice. Each advance has its own due date and a grace period after it (7 days by default). Usage draws on an advance once the credit balances that apply are spent ([spend order](#spend-order)), and keeps drawing through the grace period, up to the limit. The Billing page and the API's `notices[]` show a notice from 7 days before the due date (by default) while anything is drawn, another from the due date, and a third when the draws turn unpaid. When the grace period ends, the draws still owed become unpaid in the advance's scope, and that scope goes [on hold](#billing-holds): the clusters a restricted advance covers, or the whole organization for an organization wide advance. Paying the advance's invoice repays its draws first and closes the advance to new draws. While an advance stands on an open invoice, the invoice cannot be cancelled (`advance-open`). ## Payments A payment pays debt before it becomes credits, in this order: 1. draws on the advance tied to the invoice the payment pays; 2. unpaid, oldest first; 3. other advance draws, soonest due first. Whatever is left becomes a Standard balance. National Compute, recording a payment, can put it into a Restricted or expiring balance instead; it then pays only the debt that balance's restriction covers, or no debt when recorded that way. A card payment made on the Billing page pays debt, then becomes Standard credits. ## Promo credits Grants become Promo credits: the sign-up credits of a [public research organization](https://docs.nationalcompute.com/sign-in.md#public-research-organizations), [feedback rewards](https://docs.nationalcompute.com/api/mcp.md#feedback-rewards), [data-sharing](https://docs.nationalcompute.com/marshall-data-sharing.md#incentive) credits and promotions. A grant first pays the unpaid it can pay; the rest becomes a Promo balance. Promo credits expire, 30 days after the grant by default; a promotion can carry its own term. The Billing page shows each Promo balance's expiry date, and from 3 days before it (by default) the page and the API's `notices[]` carry a notice. At expiry, what is left of the balance is written off as a ledger row of category `expiry`, posted 15 minutes after the moment it expires: it lowers the total balance and is not spend. Unspent credits granted before Promo credits existed are moved into Promo balances once, and expire 30 days after that move; your past spending counts against those grants first. The move writes no ledger row and leaves the total balance unchanged. You will see the expiry date on your Billing page and get a notice before it. ## Restricted credits A Restricted balance pays only for what it names: clusters, sites, services, or a combination. A charge must match every kind the restriction sets (clusters and services: those services on those clusters), and any one entry within a kind. The services are compute (fixed, market and Base Load capacity), storage (shared volumes), Marshall models and the public research pool. A restriction to a site never shows the site: the Billing page and the API list your clusters there instead, and the balance reads "clusters on a site you no longer use" when none of your clusters is left there. National Compute creates Restricted balances, for example a payment recorded for one cluster or a grant for Marshall models. The Billing page shows the line each applies to ("acme-train", "Marshall models", "Storage on acme-a"). Restricted credits are spent before Promo and Standard credits, narrowest first ([spend order](#spend-order)), and count only toward the available to spend of the scopes they match: a balance for acme-train keeps acme-train running and never pays for acme-b. A payment recorded into a Restricted balance pays only the debt that restriction covers, unpaid and advance draws whose scope lies inside it ([payments](#payments)). A change to a restriction applies to charges from then on; charges already paid stay where they are. ## Billing holds A billing hold stops capacity that nothing can pay for. It opens at stage `notice`, where nothing new is placed, and turns `enforce`, where capacity is reclaimed, at its `enforce_after_ms` ([hold state](https://docs.nationalcompute.com/api/billing.md#hold-state)). - **One pool.** An organization holding only Standard credits and Promo credits with no restriction, with nothing locked, no advance and no unpaid beside its credits, is held exactly as before: when its total balance reaches zero, the whole organization goes on hold. - **Per cluster.** Any other organization is held cluster by cluster. A cluster goes on hold when unpaid usage hits it, or when its available to spend is gone while it runs paid usage. Your other clusters keep running on their own credits. Unpaid storage holds the cluster its shared volume serves; a hold never deletes data. Marshall models and the public research pool are not reclaimed: each is refused while its own available to spend, less its unpaid, is at or below zero. The hold's `units` list Marshall models while they are refused, for an organization that owes for them or used them in the last 7 days. - **Whole organization.** Unpaid with no scope, or an organization wide advance past its due date and grace, puts the whole organization on hold whatever its credit balances say. Reaching an enforced monthly spend limit holds the whole organization, as before. Credits that apply to the held scope lift its hold; so does a payment, which [pays debt first](#payments). ## Corrections The ledger is append only. A row entered by mistake is undone by a **Void**: a row of the opposite type for the same amount, whose `voids_ms` names the row it corrects. A voided charge puts its money back where it came from, or into a new Standard balance when that balance has since expired or been revoked. A voided deposit takes its credits back. Whatever of them was already spent is taken from your other credits with no restriction, soonest expiry first, then oldest, and only what those cannot cover becomes unpaid with no scope: a correction never leaves unpaid with no scope beside credits that could pay it. Debt the deposit had paid is owed again in its own scope. In the totals a Void counts in the class of the row it corrects. Voiding a charge lowers the charges, and the month's charges for the [spend limit](https://docs.nationalcompute.com/api/billing.md#balance-and-totals) in the month it is voided; voiding a deposit lowers the deposits. A **payment reversal** takes back a payment that was refunded or charged back. It takes the payment's unspent credits first, then puts back the debt the payment had paid; anything beyond that becomes unpaid in the payment balance's own scope, which for a Standard payment is no scope. As for a voided deposit, unpaid with no scope is first taken from your other credits with no restriction. Locked credits are never taken. Card refunds and card disputes are reversed automatically, and a dispute that ends with the funds returned deposits again exactly what its chargeback took ([deposit reversals](https://docs.nationalcompute.com/api/billing.md#deposit-reversals)). A **credit back** returns credits owed to you, such as an [SLA credit](https://docs.nationalcompute.com/sla.md#credit-schedule). It is a deposit of category `service_credit` that names the service period it covers. It pays debt in the scope of the charges it credits first; the rest becomes a Standard balance unless National Compute records it otherwise. It lowers the month's charges for the [spend limit](https://docs.nationalcompute.com/api/billing.md#balance-and-totals) in the month it is issued. A **revocation** removes what is left of one credit balance (a mistaken grant, abuse of a promotion). Locked credits are never revoked. Voids, revocations, expiries and payment reversals are not spend: the ledger's `category` marks each row ([categories](https://docs.nationalcompute.com/api/billing.md#categories)).