Billing basics

The model

ai.ml is prepaid. You top up in your billing currency, the money becomes USD credits, and every request settles against them. There are no monthly invoices for usage; every top-up gets an invoice.

• Credits are integers. Balances and costs are micro-USD (1_000_000 = $1). Prices are nano-USD per token. Nothing in the billing path uses floats.
• One rounding per line. Each usage line (input, output, cache read, cache write, reasoning, request fee) is tokens × nano_price → micro, rounded once. Sums are never rounded again. aiml.cost.lines in the response shows the lines.
• Pinned prices. The price version is fixed when the request is reserved and the request settles against it, even if the catalog changes mid-flight. aiml.cost.price_version names it.

Life of a charge

1. Reserve. Before the upstream call the gateway estimates the cost from your prompt and max_tokens and moves that amount from available to held. If available cannot cover it, the call fails with 402 insufficient_credits and x-aiml-required-micro tells you how much it needed.
2. Checkpoint. Long streams re-reserve as they go; a stream that exhausts the balance ends with stop reason budget_exceeded rather than running negative.
3. Settle. After the last byte, the held amount is replaced by the real cost from the provider's usage (usage.source = "provider") or, if the provider sent none, from the gateway's tokenizer (estimated). Settlement is idempotent on the request id.

GET /v1/credits returns available_micro_usd, held_micro_usd and the balance in your display currency. GET /v1/credits/ledger is the append-only ledger; add format=csv for a download.

Topping up

GET /v1/credits/topups/quote?amount_minor=… tells you what an amount buys before you pay: the booked FX rate (RBI reference rate + 0.5% for INR), tax, rail fees and the resulting credits. POST /v1/credits/topups creates the top-up and returns a hosted checkout URL (Razorpay for INR, Stripe otherwise); credits land when the payment webhook confirms.

Invoices are numbered per financial year (AIML/26-27/000001) and available as JSON, HTML and PDF under GET /v1/invoices. When the rail charges a processing fee it appears as its own line on the invoice (UPI is free; cards and Stripe pass their fee through at cost), so the invoice total always equals what you paid at checkout.

Outside India, Stripe's page offers cards, Link and whatever else the account enables. To pay with Alipay or WeChat Pay, choose it under Pay with on the console's credits page, or send "method": "alipay" or "wechat_pay" with POST /v1/credits/topups; that checkout then offers only the chosen method. Their processing fee is shown in the quote like any other.

Auto top-up

Register a mandate once (POST /v1/credits/mandates with method upi, emandate or card; Razorpay e-mandate / UPI AutoPay in India, a saved card on Stripe elsewhere) and finish the authorisation on the rail's page. Then PUT /v1/credits/auto-topup with threshold_micro and amount_minor. When the balance drops below the threshold the worker schedules a debit 24 hours ahead and announces it (topup.scheduled webhook and the billing email; that is the RBI pre-debit notification), then charges the mandate for the amount plus tax and books the top-up like any other, invoice included. The amount plus tax must fit the mandate's per-debit cap (₹15,000 without additional authentication); a debit is skipped if the balance recovered meanwhile, and three consecutive failures disable auto top-up (mandate.failed). GET /v1/credits/auto-topup shows the mandate state, the cap and any scheduled debit.

Promotional codes

A code from a promotion adds its credit to your balance: POST /v1/credits/redeem with {"code": "AIML-…"} (case, spaces, dashes and the AIML- prefix do not matter), or Redeem a code on the console's credits page. The credit is a grant line on the ledger. When the promotion says so, credit from the code expires: the response's credit_expires_at says when. Spending uses promotional credit first, soonest-expiring first, and whatever is left of it at its expiry is taken back as one expire line on the ledger (never more than your balance, and never paid credit). GET /v1/credits shows it as granted_micro_usd, with next_expiry_at and next_expiry_micro_usd; grants from ai.ml support with an expiry work the same way. An organization redeems at most one code per promotion; ten refused codes in an hour pause redemption for that hour. GET /v1/credits/redemptions lists what you have redeemed. Promotional credit is not refundable: a refund returns paid top-ups only.

Gift credit

POST /v1/credits/gifts with amount_micro_usd (at most $500) moves that much of your paid credit into a gift code, returned once in the response. Whoever redeems the code with POST /v1/credits/redeem gets the credit, and it never expires for them. A gift not redeemed within expires_days (default 90) comes back to your balance, and DELETE /v1/credits/gifts/{id} brings back an unredeemed one at once. A gift is funded from your balance less any expiring promotional credit, and only once your first payment has stood for seven days; at most 20 can be open at a time. GET /v1/credits/gifts lists yours.

Affiliate programme

When the programme is open, the console's Affiliate page (or GET /v1/affiliate) gives your organization a referral link. An organization created through it is referred by you: for the months the terms say, each of its paid top-ups earns you a commission of its credits, net of refunds, booked as a commission line on your balance once the payment has stood for 30 days. Earned commission can also be withdrawn as money, from $50 (POST /v1/affiliate/withdrawals): the amount leaves your balance at once, our finance team confirms your payment details by email and pays it, or returns it to your balance with a reason. An organization cannot refer itself, and a referral does not change anything the referred organization pays.

Invoices, credit notes and refunds

An issued invoice never changes. Corrections are credit notes (kind: credit_note, numbered AIMLCN/26-27/000001, referencing the invoice through ref_invoice_id) and, where the recipient details were wrong, a reissued invoice that names the one it replaces (reissued_from). Both show up in GET /v1/invoices next to the original.

Unused credits go back the way they came. POST /v1/credits/topups/{id}/refund with an optional amount_minor (the taxable value; omit it for everything still refundable) sends the money plus its tax to the Razorpay or Stripe payment that funded the top-up, removes the credits at the top-up's booked FX rate (a refund ledger line) and issues a credit note against the top-up invoice. A refund needs the credits to still be in your balance; the processing fee is not refundable. Pass an Idempotency-Key header to make retries safe. GET /v1/credits/refunds lists them.

Indian GST e-invoicing (IRN + QR) is generated for B2B tax invoices, credit notes and exports once it applies to the supplier; irn_status on the invoice moves from pending to generated, and the PDF is re-rendered with the IRN block.

Plans

GET /v1/plans lists the plans: Pay as you go (no fee) and the team plans, which carry a monthly fee in USD, a bundle of included credits and higher limits. Periods are calendar months.

• POST /v1/billing/subscription with plan_id moves the org. Upgrades and first subscriptions apply immediately and are prorated to the remaining whole days of the month: the fee difference is taken from your prepaid balance (plan_fee ledger line) and the included-credit difference is added (plan_credit), with a plan invoice in your billing currency.
• Downgrades, including back to pay as you go, take effect at the end of the period; you keep what you paid for until then. Choosing your current plan again cancels a scheduled downgrade.
• Renewal happens on the first of each month from the balance. If the balance cannot cover the fee the subscription is past_due; after seven days the org returns to pay as you go.

GET /v1/billing/subscription shows the current plan, period and any scheduled change.

Budgets and limits per key

Keys can carry budget.daily_micro and budget.monthly_micro, and so can the key's project; each is its own ceiling and the narrower one applies. A hard budget rejects calls with insufficient_credits code budget_exceeded.daily or budget_exceeded.monthly, and param names the ceiling that refused: budget_daily / budget_monthly for the key's own, project_budget_daily / project_budget_monthly for the project's; a soft one warns (budget_soft_exceeded, same param). The budget.threshold and budget.exhausted webhooks carry the same value as dimension. Rate limits (rpm, tpm, concurrency) are separate; see Rate limits.