Kernlift

Charge usage with credits

Users hold a credit balance from plans or grants, and metered work such as AI tasks is paid from it.

Credits are the unit your product charges for metered work. Users get them from paid plans, from an operator, or as a sign-up bonus. Each task reserves its price before it runs, and the credits are deducted only if the work succeeds. Credits need no provider and no environment variables, new users start at zero unless you turn on the sign-up bonus, and credits do not expire.

Before you begin

  • An admin account with credits.read and credits.write. To put credits on plans you also need products.write; the built-in Commerce Manager role holds the products and credits permissions.
  • For plan credits to reach buyers, a connected payment provider. See Connect a payment provider.

Give users credits

Open the plan

Go to Commerce → Products (/admin/products), click the product key and pick a plan in the Plans card.

Set the number

Enter the number in Included credits and click Save plan. Leave it at 0 for a plan that adds no credits.

When an order for that plan is paid, the buyer receives the credits once, even if the provider sends the payment event more than once. The grant reads the en plan row first, so set Included credits on the en plan and keep the other locales at the same number.

Set what work costs

AI tasks are priced in credits on Settings → AI Config: a fixed price per task, rules by request parameters, or token usage. Follow Route scenes and set pricing. A task that costs more than the available balance is rejected before the provider is called.

Charge credits for your own feature

Hold the price before the work starts, then settle the hold exactly once: capture it on success, refund it on failure. Call this from server code after you have resolved the user.

src/server/services/export.service.ts
import {
  captureAiTaskCredits,
  refundAiTaskCredits,
  reserveAiTaskCredits,
} from "@/server/services/credits-ledger.service";

const { reservationId } = await reserveAiTaskCredits({
  userId,
  taskId: `export_${jobId}`,
  amount: 5,
});

try {
  await runExport(jobId);
  await captureAiTaskCredits({ reservationId, userId });
} catch (error) {
  await refundAiTaskCredits({ reservationId, userId });
  throw error;
}

Reserving fails when the available balance is too low, and its error message contains /system/insufficient-credits so the UI can redirect. Store the reservationId next to your job so a retry or a poller settles the same hold.

Never let users change balances directly

Do not add a user-callable server function that grants, reserves, captures, refunds or repairs credits. User-facing functions only read and bind to the session user; pnpm validate:session-owner fails otherwise.

Check or repair a balance

Open the user

On Overview → Users, click Details on the user row. The Credits card shows the current balance and the latest ledger entries.

Repair if needed

If the balance no longer matches the ledger, for example after a direct database edit, click Repair snapshot. The balance is rebuilt from the ledger, and the before and after values are written to the audit log.

Verify

Grant a test user 10 credits

Grant 10 credits by hand, sign in as that user and open /app/credits. The available balance shows 10 and the ledger shows your grant.

Buy a plan

Buy a plan with Included credits in the provider's test mode, then reload /app/credits. The plan's credits appear as a purchase entry.

Sign up a new user

With the sign-up bonus on, register a new account and open /app/credits. The ledger shows one signup.bonus grant of the configured amount.

Run out of credits

Start an AI task that costs more than the remaining balance. It is not created and the user is sent to /system/insufficient-credits.

Users see the full ledger with a balanced or drift indicator at /app/credits/ledger, and holds and refunds at /app/credits/reservations. pnpm validate:credits checks the insufficient-credit path, drift repair and page wiring, and pnpm validate:signup-credits checks that the sign-up bonus is granted once and only while it is on.

Troubleshooting

A task fails with an insufficient credits error

The available balance is lower than the task's price. Credits held by tasks that are still running are not available. Grant credits or buy a plan with Included credits, then retry.

Reservation is already settled.

The hold was already captured or refunded. Settle each reservation once, and check its status before retrying a capture or refund.

The ledger page shows drift

The stored balance no longer equals the sum of the ledger, usually after a direct database edit. Open the user in the admin console and click Repair snapshot.

A paid plan did not add credits

Check that Included credits on the plan's en row is above zero and that the order is paid on Commerce → Orders. If the order is still pending, see Connect a payment provider.

Reference

Next steps