Credits and balances

A customer’s balance is the sum of their unexpired grants, minus what they’ve spent. Every grant comes from a plan, a credit pack or a manual adjustment, and Ledger records which grant each tracked use was charged to.

​

Grants

A plan allowance is the plan’s monthlyCredits; a pack grants its creditAmount. Creating a customer grants nothing. A customer can hold pack credits with no plan at all.

​

Spend order

When track records a use, Ledger spends grants in this order:

1. Plan allowances, the one that expires soonest first. After an upgrade, the old plan’s leftover credits expire first, so they’re spent before the new plan’s.
2. Credit packs and manual adjustments, the one that expires soonest first, then oldest first. Packs never expire, so they’re kept for last.
3. Overage, on a paid Sandbox plan with overage terms, up to the customer’s monthly cap.

A use that costs more than one grant holds is split across grants in that order. A use is never split between credits and a refusal: if the balance and overage together can’t cover the whole cost, track refuses it and charges nothing.

​

Worked example

A customer on Pro (1,000 credits a month) has bought one 500-credit pack, then tracks 1,200 credits of usage this period: On Dec 7 Pro renews: a new allowance of 1,000 arrives and the old one expires. The balance becomes 1,300, and the pack’s 300 credits wait until the new allowance is spent. A check reads the balance without reserving anything, so two requests can both see allowed: true for the last credit; track decides each in its own transaction, and one of them gets 409 insufficient_credits. Balances shows how to read a customer’s balance.

​

Next steps