How it works
Each movement of credits is written as an entry with an amount, a direction, the user and credit type it affects, and a reference to what caused it, such as an order, a job, or a refund. Entries are never edited after the fact; a mistake is corrected by posting a new, opposite entry. A user's balance at any moment is the sum of their entries.
The hard part is concurrency. Two requests that both read a balance of 10 and both deduct 8 must not both succeed. A ledger therefore applies the balance check and the entry in one transaction, and pairs each write with a unique key so a retried request is recognised instead of applied twice.
Example
A user buys 1,000 credits (entry +1,000), runs 40 image generations at 5 credits each (40 entries of −5, total −200), and receives a 50-credit goodwill refund (+50). The balance is 1,000 − 200 + 50 = 850, and any support question about where the credits went is answered by listing those 42 entries.
Credit ledger in Cred
Issues, deductions, and refunds in cred.diy commit the balance change together with its ledger row, so a balance does not move without a record. Keyed writes return the original result when retried, and every user's transactions can be listed through the API or seen in the dashboard.
Managing Credits docsQuestions
- Why not just store a balance column?
- A bare balance column tells you what a user has but not why. When a customer disputes a charge or a bug double-deducts, you need the history to find and reverse the exact movement. A ledger keeps that history and lets you rebuild the balance from it.
- How do I fix a wrong ledger entry?
- Post a new entry that reverses it, with a reference to the original, rather than editing or deleting the old row. The balance ends up correct and the history still shows what happened and when it was corrected.
