Credits are the most common way to price AI products. A plan includes 1,000 credits a month, each action costs a few, and the customer always knows what they have left. It is easy to explain and easy to sell.
The trouble starts with real usage, which is never flat:
A quiet month wastes credits. A customer who uses 400 of 1,000 watches 600 disappear at the reset. They paid for them, and the next time they look at the invoice they wonder why.
A bad day spends the month. An agent stuck in a loop, a leaked API key or an overeager script can burn a month of credits in an afternoon. The customer finds an empty balance and a product that stopped working.
Packs rarely match the need. A customer needs 750 credits to finish a job and your packs come in 500. They buy twice, or they leave the job unfinished.
Jobs run when nobody is watching. Agents and batch jobs run at 2 a.m. If the credits run out, the job stops and the customer finds out in the morning.
Each of these is a reason to churn that has nothing to do with the value of your product.
Four settings for credits plans
Credits plans now have four settings, one for each problem. They are independent: turn on the ones that fit your product.
| Setting | What it solves |
|---|---|
| Rollover | Unused plan credits carry over to the next period, up to a maximum |
| Credit limit | Plan credits are spent at most so many per day or per week |
| Price per credit | Customers buy any whole quantity of credits, not only fixed packs |
| Auto top-up | Commet buys more credits when the balance falls to a threshold |
Two rules apply to all of them. Plan credits are the ones the subscription grants each period. Purchased credits are the ones a customer buys, and they never expire and are never limited.
A plan with a price per credit can also allow overage: usage continues after the credits run out and the missing credits are billed at that price on the next renewal.
Balance plans have the same settings, in money instead of credits. Balance plans get the same controls covers them with their own examples.
How to set it up
All four can be edited in the dashboard: open Plans, select a credits plan and edit Credit rollover, Credit limit or Credit purchases. Here is the same with the SDK.
Roll over unused credits
await commet.plans.update({
id: "plan_pro",
unusedPlanCredits: { type: "roll_over", maxPlanCredits: 2000 },
});At each reset, the new allocation is added to the unused plan credits instead of replacing them. maxPlanCredits caps the total after the reset, including the new allocation, and must be at least the included credits of every price. Credits above it expire and fire credits.expired. { type: "expire" } restores the default. Existing subscriptions apply the change from their next reset.
Limit how fast plan credits are spent
await commet.plans.update({
id: "plan_pro",
planCreditLimit: { credits: 200, interval: "day" },
});A day window is 24 hours and a week is 7 days, starting at the time of day of the subscription's billing anchor. Past the limit, an event uses purchased credits; without enough, tracking usage returns 402 plan_credit_limit_reached until the next window. Your app gets a clear error to show instead of a silent empty balance.
Raising or removing the limit applies at once. Adding it, lowering it or changing its interval applies from the next period.
Sell any quantity of credits
Set a Price per credit and an optional Minimum purchase on the plan in the dashboard. Then:
await commet.subscriptions.purchaseCredits({
id: "sub_123",
quantity: 750,
});Commet charges the saved payment method at the plan's price per credit and adds purchased credits. Customers can also buy from the customer portal. Credit packs keep working: send creditPackId instead of quantity. Both fire credits.purchased.
Top up automatically
await commet.subscriptions.updateAutoTopUp({
id: "sub_123",
enabled: true,
threshold: 100,
quantity: 500,
maxPerPeriod: 3,
});When the subscription's credits fall to threshold, Commet buys quantity credits with the saved payment method, at most maxPerPeriod times per period. It uses the plan's price per credit, so it requires one. Customers can turn it on and edit it from the customer portal under Auto top-up.
If three top-ups fail in a row, or one charge can't be refunded, auto top-up pauses. It resumes when the payment method changes, a credit purchase succeeds or you save it enabled again. getAutoTopUp returns its status, the top-ups this period and the last failure.
Examples
Rollover for seasonal usage. A transcription app sells 1,000 credits a month with a maximum of 2,000. A podcaster who records less in December uses 400, starts January with 1,600 and spends them on the backlog. Only credits above 2,000 would expire.
A limit against runaway agents. An agent platform sells 3,000 credits a month with a limit of 200 per day. A customer's agent loops and tries to spend 1,000 credits a day. Without the limit, the month is gone on day three. With it, the agent spends 200 a day, the app shows the limit error, and the customer still has 2,400 credits on day four once they fix the loop.
Exact quantities. An image generation tool sells packs of 500 credits for $10. A customer who needs 750 would buy two packs for $20. With a price of $0.02 per credit, they buy 750 for $15.
Auto top-up for overnight jobs. A batch processing product runs a job that needs 1,800 credits on a 1,000-credit balance. With auto top-up buying 500 at a threshold of 100, Commet buys twice during the night and the job finishes. The cap of three per period keeps a mistake from turning into an unbounded bill.
Start
If you sell credits, pick the problem your customers complain about most and turn on that setting first. Read Consumption Models for rollover and limits, and Credit Packs for purchases and auto top-up.