> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runledger.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runledger.co/_mcp/server.

# How Runledger fits together

Runledger has three layers. You **configure** what work means and what it costs. Your code makes **calls** around the work. Runledger keeps **records** of what happened and what is owed. Your payment providers collect the money; Runledger decides how much.

```mermaid
flowchart LR
  subgraph Configure
    OD["Outcome definitions"]
    PL["Plans: rates, pools, allowances"]
    CT["Credit types"]
    PR["Cost models, price rules, margin guardrails"]
    SL["Spend limits"]
    PP["Payment providers and routing"]
  end
  subgraph Calls["Your code"]
    CH["check()"]
    TK["track()"]
    TC["trace()"]
    CO["checkout()"]
  end
  subgraph Records
    HO["Holds"]
    EV["Events"]
    OC["Outcome charges"]
    LE["Ledger and balances"]
    IN["Invoices"]
  end
  OD --> TK
  PL --> CH
  PL --> TK
  PR --> CH
  SL --> CH
  CH --> HO
  TK --> EV
  EV --> OC
  EV --> LE
  OC --> LE
  TC --> PR
  CO --> PP
  PP --> LE
  LE --> IN
  OC --> IN
```

## Follow one piece of work

1. **Before it starts, `check()`.** Runledger finds the customer's [subscription and plan](/concepts/billing), prices the work and runs its tests: the plan's rate, any [margin guardrail](/guides/price-rules-and-guardrails#margin-guardrails), [usage windows](/guides/usage-windows), [spend limits](/guides/spend-limits) and the balance. It answers allow or deny, and can [hold](/concepts/checks-and-holds#holds) the cost so parallel work can't spend the same credits. [Checks and holds](/concepts/checks-and-holds) has the full list of denial reasons.
2. **After it finishes, `track()`.** The event name selects what happens. A usage event draws credits from the customer's [pools](/guides/pools) or accrues a charge. An outcome event creates an [outcome charge](/concepts/outcome-settlement) that starts pending. A signal event reports something about an earlier outcome. `track()` never fails for lack of balance, because the work has happened.
3. **Around model calls, `trace()`.** It records what each call cost, so [margin per run](/guides/cost-attribution-and-margin) is revenue minus cost.
4. **Over time, clocks and rules run.** A pending charge confirms when its confirmation window closes. A [reversal rule](/concepts/outcome-settlement#reversal-rules) or a [dispute](/concepts/outcome-settlement#disputes) can reverse it until its reversal horizon closes, and then it locks.
5. **Money moves at your payment providers.** A postpaid customer gets an invoice each period. A prepaid customer buys credits through `checkout()` or an [auto top-up](/guides/auto-top-up-and-alerts). The [payment provider](/concepts/payment-providers) collects, and the result lands in the ledger.
6. **Webhooks tell you.** Each change that matters to your system is a [thin webhook](/api-reference/handle-webhooks): it names the object and you fetch its current state.

## Prepaid or postpaid

Every plan is one or the other, and the same ledger and balance formula serve both. Prepaid customers hold credits and draw them down. Postpaid customers accrue charges and receive an invoice. [Prepaid and postpaid billing](/concepts/billing) compares them.

## Sandbox and live

Every account has a sandbox and a live environment, with separate keys, data and webhook endpoints. You build and test in the sandbox, on [test clocks](/api-reference/test-in-the-sandbox) that move time forward in one call. A live configuration change goes through a [proposal](/api-reference/how-configuration-works#proposals-for-live) that a signed-in Admin approves.

## Three ways to set it up

The [dashboard](/dashboard), the API and a coding agent over [MCP](/agents/mcp) all read and write the same [configuration](/api-reference/how-configuration-works), with the same fields, validation and result. Access is by [scoped keys](/api-reference/access-and-audit), and every change records who made it.

## Where each concept is explained

Each concept has one home. Other pages link to it instead of repeating it.

| To understand                                                 | Read                                                                                               |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| The four calls, in one example                                | [Welcome](/welcome) and the [quickstart](/quickstart)                                              |
| Outcome charges, the two clocks, reversal rules, disputes     | [Outcome settlement](/concepts/outcome-settlement)                                                 |
| `check()`, holds, denial reasons                              | [Checks and holds](/concepts/checks-and-holds)                                                     |
| Plans, subscriptions, balances, credits, invoices, the ledger | [Prepaid and postpaid billing](/concepts/billing)                                                  |
| Several payment providers and routing                         | [Payment providers](/concepts/payment-providers)                                                   |
| Pricing from what each model call costs                       | [Pricing from cost](/concepts/cost-reflective-pricing)                                             |
| Refilling and capping credits over time                       | [Usage windows](/guides/usage-windows) and [pools](/guides/pools)                                  |
| Capping what a customer, team, member or agent spends         | [Spend limits](/guides/spend-limits) and [members, teams and agents](/guides/members-teams-agents) |
| Credits that buy themselves, and alerts                       | [Auto top-up and alerts](/guides/auto-top-up-and-alerts)                                           |
| Credits that lapse                                            | [Credit expiry and breakage](/guides/credit-expiry)                                                |
| Showing customers their usage                                 | [Usage meters](/guides/usage-summary) and the [customer view](/guides/customer-view)               |
| Common AI billing models, as configuration                    | [Recipes](/guides/recipes)                                                                         |
| Defining an unfamiliar word                                   | [Glossary](/reference/glossary)                                                                    |
| Moving to live                                                | [Going live](/going-live/overview)                                                                 |

## Next steps

* Run the flow once in the [quickstart](/quickstart).
* Read [outcome settlement](/concepts/outcome-settlement) and [checks and holds](/concepts/checks-and-holds), the two concepts every integration uses.