Kernlift

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.

BalanceMeaning
AvailableCredits the user can spend right now
ReservedCredits 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:

  1. Rejects an amount that is not positive.
  2. Applies the entry's change to available and reserved.
  3. Rejects the write if either balance would become negative.
  4. Appends the entry with its deltas and the balances after it.
  5. Updates the snapshot: lifetime purchased grows on grants and purchases, lifetime used on captures.
  6. Records an audit log entry.

Entries are never edited or deleted, so the ledger holds the full history of a user's credits.

OperationEntry typeAvailableReserved
Admin grantgrant+amount0
Sign-up bonus (source signup.bonus)grant+amount0
Admin deductionadjustment-amount0
Purchase (plan credits)purchase+amount0
Reservereserve-amount+amount
Capturecapture0-amount
Refundrefund+amount-amount

Hold, then capture or refund

Metered work holds the price first, then captures or refunds it:

Reservation statusReached whenLedger effect
reservedThe work starts and available covers the priceAvailable moves to reserved
capturedThe work succeedsReserved is consumed
refundedThe work failsReserved 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.

Files

src/server/services/credits-ledger.service.ts
src/server/db/repositories/credits-ledger.repository.ts
src/server/db/repositories/credits-config.repository.ts
src/components/credits/credits-workspace.tsx

Next steps