Credits ledger
How credits are stored as an append-only ledger with a balance snapshot, and how hold, capture and refund keep metered charges accurate.
Credits are the unit your product charges for metered work such as AI tasks. Every change is an entry in an append-only ledger, and the balance is a snapshot that can be rebuilt from it. To configure credits, see Charge usage with credits.
Two balances
Each user has two balances.
| Balance | Meaning |
|---|---|
| Available | Credits the user can spend right now |
| Reserved | Credits held for work that has started but not finished |
A snapshot row per user stores both, plus lifetime purchased and lifetime used totals. New users start
at zero, unless the sign-up bonus on /admin/config/auth is on.
Every change is a ledger entry
All writes go through one function that, for each entry:
- Rejects an amount that is not positive.
- Applies the entry's change to available and reserved.
- Rejects the write if either balance would become negative.
- Appends the entry with its deltas and the balances after it.
- Updates the snapshot: lifetime purchased grows on grants and purchases, lifetime used on captures.
- Records an audit log entry.
Entries are never edited or deleted, so the ledger holds the full history of a user's credits.
| Operation | Entry type | Available | Reserved |
|---|---|---|---|
| Admin grant | grant | +amount | 0 |
Sign-up bonus (source signup.bonus) | grant | +amount | 0 |
| Admin deduction | adjustment | -amount | 0 |
| Purchase (plan credits) | purchase | +amount | 0 |
| Reserve | reserve | -amount | +amount |
| Capture | capture | 0 | -amount |
| Refund | refund | +amount | -amount |
Hold, then capture or refund
Metered work holds the price first, then captures or refunds it:
| Reservation status | Reached when | Ledger effect |
|---|---|---|
reserved | The work starts and available covers the price | Available moves to reserved |
captured | The work succeeds | Reserved is consumed |
refunded | The work fails | Reserved returns to available |
A reservation settles exactly once. Capturing or refunding a reservation that is already settled, that
does not exist or that belongs to another user throws, so a retry cannot charge twice. When available
does not cover the price, the work does not start and the user is sent to /system/insufficient-credits.
How AI work uses it
- Tasks reserve the resolved channel price before the provider is called, capture on success and refund on failure. Asynchronous tasks settle when their final status arrives by webhook or poll.
- Chat reserves an estimate before the model call. When the stream ends it refunds that hold, reserves the amount priced from actual token usage and captures it immediately. If the capture fails, it refunds.
How a price is resolved is covered in AI channels, scenes and task lifecycle.
The sign-up bonus is granted once per user
When the bonus is on, the Better Auth user-create hook grants it to every new user, whichever way they sign up. The entry id is fixed per user (credit_entry_signup_<userId>), so a repeated call finds the existing entry and a concurrent duplicate fails before the balance changes. A failed grant is logged and never blocks sign-up. The switch and amount are admin settings, not environment variables; see Charge usage with credits.
Plan credits are granted once per order
When a paid order settles, the plan's included credits are added as a purchase entry with source
billing.order.<orderId>. An existing entry with that source for the same user skips the grant, so a
webhook and a callback settling the same order add credits only once. See
Payment lifecycle.
Recompute and repair
The ledger is the source of truth, so the snapshot can be checked at any time. Recomputing sums
every entry's deltas and reports whether they match the snapshot. Users can run this read-only check on
their own balance. Repairing, which needs the credits.write permission, writes the recomputed totals
back to the snapshot, rebuilds the lifetime totals and records the before and after values in the
audit log.
Expiry is not implemented
The schema accepts an expire entry type and the admin ledger can filter by it, but nothing writes
expire entries and grants carry no expiry date. Credits do not expire. Adding expiry means storing an
expiry per grant, which is a schema change in both dialects, and writing expire entries through the
same ledger function.