Concepts
Billing and credit
Prepaid credit, how amounts are written (integer nano-USD), how holds reserve credit for work in flight, and what happens when credit runs out.
Prepaid credit
You pay before you use: top up the organization's balance in the console, and every charge is taken from it. There are two kinds of credit: paid credit from top-ups, and promotional credit granted to the organization, which can expire. Promotional credit is spent along with paid credit.
GET /v1/orgs/{org_id}/billing/balance returns:
| Field | Meaning |
|---|---|
paid | Paid credit. Negative when the organization is overdrawn. |
promo | Spendable promotional credit. |
held | Credit reserved by work in flight (see holds below). |
available | paid + promo: what new work may use. |
Usage is recorded as individual usage events and rated against the price book, so every charge on the balance traces back to the usage that caused it. The cost report (GET /v1/orgs/{org_id}/usage/costs) breaks spend down by product, project and model.
Amounts are nano-USD strings
Every amount in the API is an integer number of nano-USD (one billionth of a dollar: $1 = 1000000000) sent as a decimal string, for example "1500000000" for $1.50. Per-token prices are far below a cent, so cents would round them away, and floating point would drift. Keep amounts as strings or big integers; never parse them into a float.
The SDKs format and parse them exactly:
import { formatCost, formatUsd, parseUsd } from 'hayonix';
const balance = await client.billing.getBalance(); // the key's org is filled in for you
console.log('available:', formatUsd(balance.available)); // e.g. "$25.00"
console.log('exact:', formatUsd(balance.available, { maxDecimals: 9 }));
console.log('a tiny charge:', formatCost('184331')); // "<$0.01"
console.log('$5 in nano-USD:', parseUsd('5')); // "5000000000"Holds
Work whose final cost is not known yet reserves credit first. An inference request holds its worst-case cost while it runs and settles at its real token count; a fine-tuning job holds its estimated cost when it is created. If the hold cannot be made, the request is refused with 402 and type insufficient_credit_error before anything runs.
When credit runs out
An organization is out of credit when available is zero or less. Then:
- new launches, inference requests, jobs and batches are refused with
402; - running compute (pods, serverless workers, dedicated endpoints) keeps running for a grace period of 60 minutes so you can top up without losing work, then it is stopped. Volumes are kept, and a warning goes out shortly before the stop. Spending fast enough to overdraw the balance by a large amount stops compute sooner;
- when credit is back above zero, new work can start again at once. Compute that was stopped stays stopped until you start it.
You can also set spend limits on the organization: one for the trailing hour and one for the calendar month. An alert goes out at 80 % of a limit. Reaching one refuses new billable work with 402 and code spend_limit_reached and stops running compute the same way as running out of credit; the limit clears by itself when the window moves on or when you raise it. Auto-recharge tops up from a saved card when the balance falls below a threshold, at most once every 10 minutes and up to a monthly cap.
Credit is only granted by payments
A top-up becomes credit when the payment processor confirms the payment, never when a checkout page redirects back. That can take a few seconds after you pay.