> ## Documentation Index
> Fetch the complete documentation index at: https://getlago.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit ledgers

> Credits bought, granted, spent and expired, and what your customers still hold.

What is happening in my customers' wallets? This report covers credits bought, credits given away, credits spent, credits expired, and what is left on the books.

<Warning>
  **A top-up is a prepayment, not a sale.** The customer pays you before you have delivered anything, so the cash sits as money you owe them in product. You earn it as they spend the credits on usage. That is why the top-up is kept out of [Revenue streams](/docs/guide/analytics/revenue/revenue-streams): counting the top-up and the usage it later pays for would count the same money twice.
</Warning>

## Money or credits: pick one first

Every chart here has two readings, controlled by the **Credits metric** filter.

| Setting                  | You are looking at                            |
| ------------------------ | --------------------------------------------- |
| **Amount** (the default) | 💰 Money, in the wallet's currency            |
| **No. of credits**       | 🔢 Billing units, the number of credits moved |

They are not interchangeable. A wallet priced at 1 credit for 2 USD reports the same movement as 50 credits or as 100 USD. Always say which one you are quoting.

## What's on this dashboard

| Chart                   | What it answers                      | Values           | Behaviour |
| ----------------------- | ------------------------------------ | ---------------- | --------- |
| Credit ledger movements | What went in and out of the wallets? | 💰 or 🔢         | Activity  |
| Purchased credits       | What did customers buy?              | 💰 or 🔢         | Activity  |
| Offered credits         | What did I give away?                | 💰 or 🔢         | Activity  |
| Credit balances         | What do customers still hold?        | 🔢 Billing units | Balance   |
| Prepaid credits details | The same movements as a table        | 💰 or 🔢         | Activity  |

Movements are **activity**, like a bank statement: each value covers the period it sits in. A balance is what is **left** at the end of the period, not what came in during it, so the balance at the end of your date range is what customers held then.

## The four kinds of movement

| Type              | Direction | What it is                                                                                            |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| Purchased credits | In        | The customer prepaid. Cash now, earned as they spend it                                               |
| Offered credits   | In        | You granted credits: a trial, a goodwill gesture, a commercial deal. They cost you revenue when spent |
| Consumed credits  | Out       | Credits spent on an invoice                                                                           |
| Voided credits    | Out       | Credits removed from the wallet, by expiry or by hand. Expiry never creates revenue                   |

On the ledger chart, the two outflows are drawn below zero so it reads like a ledger.

|                                           | Counted? | If not, where is it?                                                                             |
| ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| A wallet transaction that has settled     | ✅ Yes    |                                                                                                  |
| A wallet belonging to a partner account   | ✅ Yes    |                                                                                                  |
| A top-up still pending, or that failed    | ❌ No     | The wallet itself, see [Wallets and prepaid credits](/docs/guide/wallet-and-prepaid-credits/overview) |
| The revenue earned when credits are spent | ❌ No     | [Revenue streams](/docs/guide/analytics/revenue/revenue-streams)                                      |

## Credit balances

What your customers still hold. A month with no activity carries the previous balance forward, so a dormant wallet still shows its balance.

<Note>
  **A credit balance is a liability.** It is product you owe your customers, like a gift card that has not been spent. Watch it when credits are sold in bulk and spent slowly.
</Note>

The newest month stays empty until the numbers update overnight.

## Filters

| Filter               | What it does                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| Date range           | Sets the period. With nothing set, the movement and inflow charts show the current calendar year |
| Granularity          | Sets the bar width: day, week or month                                                           |
| Credits metric       | Switches every chart between 💰 Amount and 🔢 No. of credits                                     |
| Currency             | Keeps one wallet currency                                                                        |
| Country              | Keeps customers in one country                                                                   |
| Customers            | Keeps one or more named customers                                                                |
| Customer type        | Keeps companies or individuals                                                                   |
| Plan code            | Keeps credits linked to one plan                                                                 |
| Subscription ext. ID | Isolates a single subscription                                                                   |
| Customer has tax ID  | Keeps customers with, or without, a tax ID on file                                               |

⚠️ **Prepaid credits details ignores every customer and plan filter.** Country, Customers, Customer type, Plan code, Subscription ext. ID and Customer has tax ID do not change it. Use the ledger movements chart when you need those cuts.

<Warning>
  **Splitting credits by plan or subscription is an estimate.** A wallet belongs to a customer, not to a subscription. When a transaction is tied to an invoice covering several subscriptions, its value is divided evenly across them. Customer and currency figures are exact.
</Warning>

## What's not included (for now)

* **Unsettled top-ups.** A purchase that never settled is invisible here, even if the customer was invoiced for it.
* **Revenue.** Nothing on this page is revenue. See [Revenue streams](/docs/guide/analytics/revenue/revenue-streams).
* **The top-up invoice itself.** It appears as a credit-type invoice on [Invoices](/docs/guide/analytics/invoices).
* **Money for the Credit balances chart.** Balances are reported in credits only.

## Common questions

<AccordionGroup>
  <Accordion title="A customer bought 10,000 of credits. Why didn't revenue move?">
    Because the money is prepaid, not yet earned. It shows here as a purchased-credit inflow, and on [Invoices](/docs/guide/analytics/invoices) as a credit-type invoice. You earn it as the customer spends the credits, which is where it reaches [Revenue streams](/docs/guide/analytics/revenue/revenue-streams).
  </Accordion>

  <Accordion title="Why do prepaid credits show as contra revenue?">
    Because the invoice they paid for already reported the full amount as gross revenue. Deducting the credits spent stops the same money being counted twice.
  </Accordion>

  <Accordion title="What is the difference between offered and purchased credits?">
    Purchased credits are cash you received against a liability. Offered credits are a discount you have not given yet: they cost you nothing when granted, and reduce revenue when spent.
  </Accordion>

  <Accordion title="Why don't twelve monthly balances add up?">
    Because a balance is not an amount earned. December's balance is the year-end balance. To measure a year's activity, use the ledger movements.
  </Accordion>

  <Accordion title="Why is a top-up missing?">
    It has probably not settled yet. Only settled transactions appear here. Check the wallet's transaction list in the app.
  </Accordion>
</AccordionGroup>
