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

# Credits and balances

> Where a customer's credits come from, when they expire, and the order Ledger spends them in.

A customer's balance is the sum of their unexpired **grants**, minus what they've spent. Every grant comes from a plan, a credit pack or a manual adjustment, and Ledger records which grant each tracked use was charged to.

## Grants

| Grant | Arrives | Expires |
| - | - | - |
| Free plan allowance | When you attach the plan, then each month | End of its period |
| Paid plan allowance | When Stripe confirms the first payment, then with each renewal invoice | End of its period |
| Credit pack | When Stripe confirms the payment | Never |
| Manual adjustment | When you [add it](https://docs.integrateledger.com/customers/balance-adjustments.md) | When you choose, or never |

A plan allowance is the plan's `monthlyCredits`; a pack grants its `creditAmount`.

Creating a customer grants nothing. A customer can hold pack credits with no plan at all.

## Spend order

When [`track`](https://docs.integrateledger.com/api-reference/usage/track) records a use, Ledger spends grants in this order:

```mermaid theme={"system"}
%%{init: {"theme": "base", "themeVariables": {"fontFamily": "IBM Plex Sans, sans-serif", "fontSize": "14px", "primaryColor": "#f7f6f3", "primaryBorderColor": "#c4bfb5", "primaryTextColor": "#1a1816", "lineColor": "#6b655c", "edgeLabelBackground": "#ffffff"}}}%%
flowchart LR
    plan["1 · Plan allowance"] -- "used up" --> packs["2 · Credit packs"]
    packs -- "used up" --> overage["3 · Overage<br/>paid plans"]
    overage -- "cap reached" --> refused["Refused · 409"]
    style plan fill:#eff2fd,stroke:#2443c4
```

1. **Plan allowances**, the one that expires soonest first. After an [upgrade](https://docs.integrateledger.com/configure-pricing/upgrades-and-downgrades.md), the old plan's leftover credits expire first, so they're spent before the new plan's.
2. **Credit packs and manual adjustments**, the one that expires soonest first, then oldest first. Packs never expire, so they're kept for last.
3. **Overage**, on a paid Sandbox plan with [overage](https://docs.integrateledger.com/configure-pricing/overage.md) terms, up to the customer's monthly cap.

A use that costs more than one grant holds is split across grants in that order. A use is never split between credits and a refusal: if the balance and overage together can't cover the whole cost, `track` refuses it and charges nothing.

## Worked example

A customer on Pro (1,000 credits a month) has bought one 500-credit pack, then tracks 1,200 credits of usage this period:

| Grant | Granted | Spent | Left |
| - | - | - | - |
| Pro allowance, Nov 7 – Dec 7 | 1,000 | 1,000 | 0 |
| Top-up pack | 500 | 200 | 300 |
| **Balance** | | | **300** |

On Dec 7 Pro renews: a new allowance of 1,000 arrives and the old one expires. The balance becomes 1,300, and the pack's 300 credits wait until the new allowance is spent.

A check reads the balance without reserving anything, so two requests can both see `allowed: true` for the last credit; `track` decides each in its own transaction, and one of them gets `409 insufficient_credits`. [Balances](https://docs.integrateledger.com/customers/balances.md) shows how to read a customer's balance.

## Next steps

> [card] [Gating features](https://docs.integrateledger.com/getting-started/gating.md)
>
> Gate features on the balance and record each use once.

> [card] [Billing lifecycle](https://docs.integrateledger.com/concepts/billing-lifecycle.md)
>
> When paid grants arrive, renew and end.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.