Skip to main content
UnitPay is the billing engine where dollars and credits are both first-class. Most billing tools bolt credits on as an afterthought; here they run on the same catalog, the same subscriptions, and the same APIs as dollar billing — they’re just a different way value moves out of the core. This page is the hub for the credit path: how it works, when to reach for it, and where to go next.

​
Two paths, one core

You model what you sell once and attach customers to it. From there, usage flows down one of two paths: The difference is when money settles:
Dollar billingCredit billing
SettlesAt invoice time — usage aggregates and is billed at the end of the cycleAt track time — the balance is deducted the moment usage is reported
Customer holdsA running tab that becomes an invoiceA prepaid balance that draws down
Runs out of money byNon-payment of an invoiceHitting a zero balance
Real-time gateEntitlement checkcheck against remaining balance
A single plan can do both — a dollar price for the subscription and a credit grant that refills every cycle.

​
The credit path, step by step

1

Track

Your app reports what happened — a message sent, a token consumed, an API call made — with track. This is the same call the dollar path uses; UnitPay routes it by how the plan is priced. See the two verbs.
2

Resolve the charge

UnitPay converts the raw usage into a credit cost. In a credit system, each feature has a credit cost per unit — 6 premium messages at 3 credits each resolves to 18 credits.
3

Deduct FIFO

The resolved cost is deducted from the customer’s open grants in priority order, FIFO within a priority. Expiring grants are spent before permanent ones, so nothing is wasted.
4

Ledger

Every grant and every deduction is written to the append-only ledger. The customer’s balance is always the sum of their open grants — never a number you mutate directly.

​
When to reach for credits

Credits fit when the customer pays (or is granted) before they use, and value is consumed action-by-action:
  • Recurring allowances — “1,000 credits/month” that refill each cycle, burned per message or per action (Lovable-style).
  • Prepaid balances — “$10 of credit” bought upfront and drawn down per token in dollars (Anthropic-API-style). See Denominations for the unit-vs-fiat distinction.
  • Daily free drips on top of a paid allowance.
  • Metered work with an unknown cost — reserve a budget, then reconcile. See Reserving before you spend.
Reach for dollar billing instead when the customer is invoiced for whatever they use at the end of the cycle — see Billing. You don’t have to choose globally: pick per feature, and mix both on one plan.

​
Explore the credit path

Denominations

Unit credits vs. fiat credits — and the rule never to mix them.

Grants & priority

What a grant is, the priority convention, and FIFO tie-breaks.

Wallets & the ledger

Credit accounts, their lifecycle, and the append-only record.

Top-ups

Refill a balance manually, automatically, or by credit package.

Run it end to end

The Quickstart: grant credits, spend them, read the ledger.

React credit hooks

Render balances, ledger, top-ups, and burn in your app.