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.readandcredits.write. To put credits on plans you also needproducts.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.
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
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.
Publish content with the CMS
Write, publish and organise blog posts, legal pages, a changelog and a roadmap in English and Chinese from the admin console.