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.

Follow one piece of work

1. Before it starts, check(). Runledger finds the customer’s subscription and plan, prices the work and runs its tests: the plan’s rate, any margin guardrail, usage windows, spend limits and the balance. It answers allow or deny, and can hold the cost so parallel work can’t spend the same credits. 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 or accrues a charge. An outcome event creates an outcome charge 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 is revenue minus cost.
4. Over time, clocks and rules run. A pending charge confirms when its confirmation window closes. A reversal rule or a dispute 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. The payment provider collects, and the result lands in the ledger.
6. Webhooks tell you. Each change that matters to your system is a thin webhook: 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 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 that move time forward in one call. A live configuration change goes through a proposal that a signed-in Admin approves.

Three ways to set it up

The dashboard, the API and a coding agent over MCP all read and write the same configuration, with the same fields, validation and result. Access is by scoped keys, 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.

Next steps

• Run the flow once in the quickstart.
• Read outcome settlement and checks and holds, the two concepts every integration uses.