For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inGet Paid
DocumentationAPI ReferenceCLI
DocumentationAPI ReferenceCLI
  • Getting Started
    • Quickstart
    • First signals
    • Cost traces
    • Cost attributed signals
    • Delivered value
  • Credits
    • How credit balances work
    • Understanding the credit ledger
    • Examples of plans with included credits
  • Customers & Users
    • Checkout
    • User management
    • Multi-entity customers
  • Billing
    • Webhooks
    • Product lifecycle and archival semantics
    • Backdated order activation
  • Value Receipts
    • Overview
    • Integration guide
    • Authentication and embedding
  • Integrations
    • Datadog
    • Xero
LogoLogo
Log inGet Paid
On this page
  • Overview
  • What appears in the ledger
  • Common sources of ledger activity
  • Balance before and after
  • Pending grants
  • How the ledger relates to credit allocations
  • Common support scenarios
Credits

Understanding the credit ledger

Was this page helpful?
Previous

Examples of plans with included credits

Next
Built with

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.

Balance before and after

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

Example:

TimeEventAmountBalance change
09:00Monthly allocation granted+1,0000 -> 1,000
11:15Usage recorded-1201,000 -> 880
14:20Manual top-up granted+200880 -> 1,080
17:45Usage recorded-801,080 -> 1,000

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:

TimeEventAmountEffect
10:00Invoice issued for top-up+500Pending, not yet available
13:30Invoice paid+500Moves into available balance

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.