A balance plan sells usage in money. The plan includes $50 a month, every message, call or API request has a price, and the customer spends from that amount. It works for products where each action costs something different and a credit would be one more unit to explain.
Like credits, a fixed amount runs into usage that is never flat:
A slow month loses money. A shop that sends fewer SMS campaigns in February watches the unused part of its $50 disappear at the renewal.
A compromised account spends it in hours. A stolen login on a calling platform can dial premium numbers all night. By morning the month's balance is gone.
Fixed top-ups don't match the bill. A customer who needs $35 to finish the month has to pick between $20 and $50.
Work stops when the balance hits zero. A rendering job or a delivery route doesn't wait for someone to top up.
The credits controls now work in money
Balance plans now have the same settings as credits plans, with amounts instead of credits.
| Setting | What it solves |
|---|---|
| Balance rollover | Unused plan balance carries over to the next period, up to a maximum |
| Balance limit | Plan balance is spent at most so much per day or per week |
| Balance top-ups | Customers add any amount above a minimum you set |
| Auto top-up | Commet adds balance when the total falls to a threshold |
| Overage | Usage continues past zero and the missing amount is billed at renewal |
Every balance now has two parts. The plan balance is what the subscription grants each period. The purchased balance is what the customer adds with top-ups and what you add with adjustments. Usage spends the plan balance first, and the purchased balance is never limited and is kept until the subscription ends.
How to set it up
In the dashboard, open Plans, select a balance plan and edit Balance rollover, Balance limit, Balance top-ups or Overage. Through the API, plan amounts are in USD cents and convert to each currency with the plan's exchange rate, unless you set a custom amount for that currency under Plan balance terms.
Roll over unused balance
curl -X PATCH https://commet.co/api/v1/plans/plan_pro \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{ "unusedPlanBalance": { "type": "roll_over", "maxPlanBalance": 15000 } }'At each renewal the new plan balance is added to what was left. maxPlanBalance caps the plan balance after the reset, including the new amount, and must be at least the included balance of every price. Anything above it expires and fires balance.expired. Existing subscriptions apply it from their next reset.
Limit how fast plan balance is spent
curl -X PATCH https://commet.co/api/v1/plans/plan_pro \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{ "planBalanceLimit": { "amount": 1000, "interval": "day" } }'A day is 24 hours and a week is 7 days, starting at the time of day of the subscription's billing anchor. Past the limit, usage is paid from the purchased balance. Without enough, tracking usage returns 402 plan_balance_limit_reached until the next window. Raising or removing the limit applies at once. Adding it, lowering it or changing its interval applies from the next period.
Let customers top up any amount
Turn on Allow top-ups and set an optional Minimum top-up. Customers top up from the customer portal, or you do it for them:
await commet.subscriptions.topupBalance({
id: "sub_123",
amount: 3500,
});The amount is in cents of the subscription's currency. Commet charges it plus tax, adds it to the purchased balance, records the invoice and fires balance.topped_up. The effective minimum is the plan's minimum in that currency, raised to the currency's minimum charge. With top-ups off, the portal hides the button and the API rejects the top-up.
Top up automatically
curl -X PATCH https://commet.co/api/v1/subscriptions/sub_123/auto-top-up \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{ "enabled": true, "threshold": 500, "amount": 2000, "maxPerPeriod": 10 }'When the total balance falls to threshold, Commet charges amount plus tax to the saved payment method, at most maxPerPeriod times per period. Both are in cents of the subscription's currency. Customers can set it up themselves in the portal under Auto top-up. After three failed top-ups in a row, or one whose charge couldn't be refunded, it pauses, and it resumes when the payment method changes, a top-up succeeds or you save it enabled again.
Bill overage instead of stopping
curl -X PATCH https://commet.co/api/v1/plans/plan_pro \
-H "Authorization: Bearer ck_..." \
-H "Content-Type: application/json" \
-d '{ "blockOnExhaustion": false }'Usage keeps working after both parts reach zero, and the missing amount is billed on the next renewal invoice. A top-up pays back that debt first. Trials and free plans always stop at zero.
Examples
Rollover for a seasonal shop. An SMS marketing platform includes $50 a month with a maximum of $150. A clothing store that sends little in February keeps $35 of its balance, starts March with $85 and spends it on the autumn launch. Only what goes above $150 would expire.
A daily limit against toll fraud. A calling platform for support teams includes $300 a month with a limit of $10 a day. Someone gets into a customer's account and starts dialing premium numbers. The plan balance stops after $10 that day. The customer has no purchased balance, so the next calls are rejected with the limit error, and they still have the rest of the month once the account is secured.
The exact amount, in local currency. A data enrichment API for sales teams sets a $5 minimum top-up. A customer in Argentina sees the minimum converted to pesos, or the amount you set for ARS, and tops up exactly what the quarter's prospecting needs instead of a fixed pack.
Auto top-up for long renders. A cloud rendering service runs a client's animation overnight. With auto top-up at $5, adding $20, the job keeps going as the balance drains, and the limit of ten per period keeps a bad render queue from becoming an unbounded bill.
Overage for enterprise accounts. A maps API sells to logistics companies whose drivers can't stop mid-route. Its plans allow overage, so a busy week goes past the included balance and the difference appears on the next invoice, the way their finance team already expects.
What to know
Renewals, plan changes and resumes reset the plan balance with the plan's rollover terms. The purchased balance stays.
Adjustments from the dashboard or the API go to the purchased balance and fire
balance.granted.Reads return both parts: the subscription's
balancehasplan,purchasedandtotal.Turning top-ups off stops new top-ups and auto top-up. Customers keep the balance they already have.
Start
If you sell usage in money, start with the setting that answers your customers' most common complaint. Read Balance and Top-Ups for the full reference.