Billing API notes

These notes complement the Billing section of the API reference and the Pricing and billing page. All amounts are USD; each money field is a six-decimal string plus an exactly equal integer micro-USD value.

Endpoints

How the balance is computed

Amounts are integer micro-dollars. paid is signed posted paid credit (it can be negative after a payment reversal); promo is non-negative posted promotional credit. Let P = paid + promo. negative = max(0, -P) is the positive size of any debt, not another amount to subtract. open_accruals is the estimated cost of usage that has not been posted yet. balance = min(P, max(0, P - O)) where O is open_accruals: estimated usage can use up your funds but cannot create debt. Starting or resuming a computer and the runway estimate use balance.

The ledger's amount is the signed change in P; balance_after is P immediately after the transaction, excluding open estimates. /billing/usage and balance.month_to_date include posted usage plus still-open estimates (never both for one interval); funding, grants, refunds and reversals are excluded. Compute includes on-demand and always-on; storage includes each computer's own storage and account storage; egress is billable outbound traffic. For group_by=computer account-level storage and egress appear as one group with computer_id: null. group.total = compute + storage + egress, and response.total is the sum of the groups.

Example: with paid = $10, promo = $2 and open_accruals = $3, P = $12 and balance = $9. After that usage posts, the ledger shows an amount of -$3.00 with balance_after = $9.00, and open_accruals is $0.

Runway and the zero-balance timeline

runway_seconds is the projected time to zero including open storage and egress accruals and the next month's cap reset. It is null only when nothing can accrue; if the projected timestamp cannot be represented, runway_ends_at is null and runway_seconds is capped at 10 years.

zero_balance_timeline is {paused_at, notices:[{day, sent_at, accepted}], capacity_release_at, deletion_eligible_at, deletion_held_reason}. A notice counts as accepted only with evidence that your mail server accepted the message; that is not proof that a person read it. Warning thresholds re-arm when funding restores runway above them. See What happens at low balance.

Top-up statuses

The state is derived from verified payment evidence, not from the order in which notifications arrive. Only new and processing occupy your one open-invoice slot. A non-final invoice reserves its not-yet-credited amount against the $2,000 headroom; excess payment is a separate liability until refunded or converted. Breaking a top-up rule returns 422 topup_limit. expires_at is authoritative for every method.

Rules: on-chain and any need at least $20; at most $250 per top-up in the first 30 days, then $1,000; posted funds plus outstanding invoice reservations at most $2,000; one open invoice per account.

Spend limit

API keys can keep or strengthen both the amount and the action: lower or keep a finite amount, set a finite amount where none is set, and keep pause or change notify to pause. Raising or removing a finite limit, or changing pause to notify, needs a fresh second-factor check in the console; otherwise the API returns 403 forbidden_scope. A spend-limit pause ends at the next UTC month or when you raise or remove the limit; computers do not start automatically. Invalid values return 422; malformed JSON or a non-JSON content type returns 400.

Refunds

Refunds are requested in the console and sent by us; there is no refund API. Refund eligibility and amounts are described on the Pricing and billing page.

Dory is in development; these pages describe the planned service and may change. Questions: support@computeengines.com.