The credit model
How a tenant's credits work — free daily credits, the monthly grant, top-ups, and rollover — and exactly when each one is billed to your platform account.
Every AI build a tenant runs spends credits. As the reseller you decide how many credits each tenant gets and when, through entitlements (or a named plan). This page explains the four credit pools, when each one is billed to your platform account, and which endpoint touches which.
The four pools
Each tenant's standing balance is made of four distinct pools. You can read them live in the balances block of usage.
Prop
Type
When each pool is billed
The principle: you are billed when a credit is committed to a tenant, except for free daily credits, which you are billed for only as they are consumed.
| Pool | Billed | Capped | Notes |
|---|---|---|---|
| Free daily | On consume | credits_per_day per day | Only the credits the tenant actually spends are charged. Unused daily allowance is never billed. |
| Monthly | On assign | monthly_credit_cap | Charged in full when the grant lands at the start of a cycle. |
| Top-up | On assign | — | Charged when added via topup. |
| Rollover | Never (already charged) | derived from rollover_months | Unused monthly credits carried forward; re-charging would double-bill. |
Monthly and top-up credits are billed when granted, not when used
Free daily credits are pay-as-you-go. Monthly and top-up credits are pay-on-grant: once you assign them to a tenant they are billed to your platform account regardless of whether the tenant spends them. Size the monthly grant to match what you actually charge the customer.
Spend order
When a tenant runs a build, credits are drawn in this order:
- Free daily credits — up to that day's
credits_per_dayallowance. - Monthly credits (the current grant, then any rollover from prior cycles).
- Top-up credits.
So a tenant only dips into the paid pools after exhausting the free daily allowance.
How each endpoint touches credits
| Endpoint | Effect on credits |
|---|---|
create | Provisions the tenant with its initial entitlements (or a plan_code). The monthly grant is set up here; the first grant lands per the plan. |
plan | Changes the caps. With a plan_code it rewrites the credit knobs (monthly_credits, credits_per_day, rollover_months, …) from the named plan. With raw entitlements it replaces only the keys you send. A plan change does not itself re-grant — the new monthly size takes effect at the next refresh. |
plan-refresh | The cycle boundary. Rolls unused monthly credits forward per rollover_months, resets the monthly grant to monthly_credits, and resets the daily/monthly free-credit counters. This is when the next monthly grant is billed. Idempotent per (tenant, cycle_anchor). |
topup | Adds purchased top-up credits to the tenant (billed on assign). Idempotent on idempotency_key. |
Read live balances from usage
The current size, used, and remaining figures for every pool — plus rollover
expiry and the live caps — are returned in the balances block of
usage. Treat balances: null as "unavailable", not "zero".
See also
- Entitlements — the per-tenant caps that define the pools.
- platform-plans — your named plans, addressable by
plan_code. - Data model — why the bill always meters to your platform account.
Entitlements
The per-tenant budget caps you set with create and plan. A JSONB object of known knobs — invalid keys and values are dropped silently, never rejected.
Idempotency
How each endpoint behaves on retry — which carry an idempotency key, which are idempotent by state, and how to treat a terminated tenant.