Understanding the credit ledger | Paid

Overview

The credit ledger is the running history behind a customer’s balance. Instead of treating credits as a single opaque number, the ledger answers the operational questions customers and support teams usually ask:

When were credits added?
What consumed them?
Were credits pending before payment?
Why did the balance change from one value to another?

You can think of the ledger as the audit trail for a customer’s prepaid credit activity.

What appears in the ledger

Each ledger entry represents a credit movement for a specific credit currency. In practice, entries typically fall into three categories:

Grant: credits were added and became available
Spend: credits were consumed by usage
Pending grant: credits were expected, but not yet usable because they were waiting on payment or activation

This makes it possible to explain the difference between credits that are already usable and credits that have been promised but are not yet spendable.

Common sources of ledger activity

Customers usually see ledger activity from:

Prepaid purchases
Plan renewals that include a fresh credit allowance
Manual top-ups or promotional grants
Usage events that spend credits
Corrections or adjustments to an earlier credit allocation

The ledger gives these events an ordered history, so support and finance teams can understand not just the current balance, but how it got there.

Grants for a partial billing period are prorated to the exact share of the period, at up to six decimal places. A 10-credit monthly allowance joined 11 days before the cycle ends grants 3.666666 credits, not 3.

Balance before and after

A useful way to read the credit ledger is as a sequence of balance transitions.

Example:

Time	Event	Amount	Balance change
09:00	Monthly allocation granted	`+1,000`	`0 -> 1,000`
11:15	Usage recorded	`-120`	`1,000 -> 880`
14:20	Usage recorded	`-0.5`	`880 -> 879.5`
16:10	Manual top-up granted	`+200`	`879.5 -> 1,079.5`
17:45	Usage recorded	`-79.75`	`1,079.5 -> 999.75`

Amounts and balances are decimal, exact to at most six decimal places, so a single sub-unit spend moves the balance off a whole number and it stays there. A ledger reader must not assume the “before” and “after” values are integers. See Credit precision.

This is often the fastest way to explain a customer’s available balance at any point in time.

Pending grants

Some businesses make credits available only after payment. In that setup, the ledger can show a pending grant before the customer actually gains usable credits.

Example:

Time	Event	Amount	Effect
10:00	Invoice issued for top-up	`+500.5`	Pending, not yet available
13:30	Invoice paid	`+500.5`	Moves into available balance

A pending grant carries the same exact decimal amount it will have once it becomes available; payment moves it between states without changing the number.

This distinction helps avoid confusion when a customer has purchased credits but cannot use them yet.

How the ledger relates to credit allocations

Credit allocations and the ledger answer different questions:

Credit allocations explain where available credits currently live and which rules apply to them
The ledger explains how the balance changed over time

Both views are useful:

Use the balance and allocation view to power product logic and customer-facing remaining-credit displays
Use the ledger view when you need historical context, support diagnostics, or finance explanations

Common support scenarios

The credit ledger is especially useful when answering questions like:

“Why did my balance drop this morning?”
“Why are my new credits not available yet?”
“Did my promotional credits get used first?”
“Why does my balance still look low after an adjustment?”

These are usually difficult to answer from a single balance snapshot alone, but straightforward when you can read the ledger chronologically.