Glossary
One definition for each term the docs use, with the page that explains it.
Each term has one meaning across these docs and the API reference. The last column names the page that explains it in full.
| Term | Meaning | Read more |
|---|---|---|
| Account | Your Runledger workspace. It has a sandbox and a live environment with separate keys and data. | Sandbox and test clocks |
| Actor | Who made a change: a user, an agent, a key, a rule or system. Runledger fills it in from the credential. | Access, actors and audit |
| Admin | One of the two dashboard roles. An Admin manages the team, live keys, payment providers, going live and billing configuration, and approves proposals. A team can have several. | The dashboard |
| Agent | In billing, your label (agent_id) for the software doing the work, so usage and limits can be attributed to it. Separately, an agent key is a restricted key issued to a coding agent. | Members, teams and agents, MCP servers |
| Allowance | A usage window on a plan. Its kind is refill, which grants credits at the start of each window, or cap, which limits use in the window. | Usage windows |
| Auto top-up | A standing rule on one customer: when a pool falls to a threshold, buy credits to bring it back to a target. | Auto top-up and alerts |
| Balance | What a customer can still use. The formula is available = posted - held + limit, for both billing modes. | Prepaid and postpaid billing |
| Breakage | Credits that lapsed unused, reported as included, promotional or paid. | Credit expiry and breakage |
| Burn multiplier | A factor, set on a pool or a rate, that changes how many credits a unit of work draws. | Pools |
| Catalog | The read-only provider price catalog that Runledger maintains: provider models and their versioned prices. | Catalog, cost models and overrides |
| Charge | Short for an outcome charge. Usage charges are accruals or credit draws and have no separate object. | Outcome settlement |
| Check | The check() call: allow or deny work before it starts, and optionally hold its cost. | Checks and holds |
| Checkout session | A hosted page where a customer buys a plan or credits. Created with checkout(). | Prepaid and postpaid billing |
| Collaborator | One of the two dashboard roles. A Collaborator does the day-to-day work and proposes live changes for an Admin to approve. | The dashboard |
| Configuration document | One document that holds credit types, outcome definitions, plans, endpoints, rules, spend limits, account settings, cost models, price rules and guardrails. Payment providers are connected on their own. You validate, dry-run, apply and propose it. | Configuration |
| Confirmation window | How long a new outcome charge stays pending before it confirms. Set on an outcome definition. | Outcome settlement |
| Cost model | What you pay for one provider’s model: its units, dimensions and rate cards. Its source is catalog or custom. | Catalog, cost models and overrides |
| Credit grant | A batch of credits given to a customer, with its pool, expiry and priority. It is paid, with a cost basis, or promotional. | Prepaid and postpaid billing |
| Credit type | The unit a prepaid plan counts in, such as ai_credits. Each prepaid plan has one, and balances in different credit types are never added together. | Prepaid and postpaid billing |
| Customer | Your customer, usually an organization. You can send your own ID as external_id. | Conventions |
| Customer session | The API object that opens the customer view for one customer. Its link expires after an hour by default. | Customer view |
| Customer view | A Runledger-hosted page where your customer sees their usage and manages their own limits. It is not the dashboard. It can carry your logo, name and accent color. | Customer view |
| Dashboard | The web app for your team to see what happened and act on it. Your end customers don’t see it. | The dashboard |
| Dispute | A complaint about an outcome charge, decided by you and your team. When nobody decides by the deadline, the default decision applies. | Outcome settlement |
| Event | A call to track(). Its kind is usage, outcome, signal or unpriced, set by what its name means in your configuration. Once recorded, it never changes, including its name. | Welcome |
| Hold | An amount reserved by check() so parallel work can’t spend the same balance. track() turns it into the real charge. | Checks and holds |
| Idempotency key | A key that makes a retry safe. Writes use the Idempotency-Key header. Events and costs use an idempotency_key field on each item. | Idempotency and errors |
| Invoice | A postpaid customer’s bill for one period. It stays a draft until finalizes_at, then never changes. | Prepaid and postpaid billing |
| Ledger | The immutable list of every credit and money movement. A correction is a new entry linked to the one it corrects. | Prepaid and postpaid billing |
| Live | The environment that carries real billing. Configuration reaches it through a proposal when an agent writes it. | Going live |
| Margin guardrail | A margin floor for some of your work, with an action of warn or block. | Price rules and margin guardrails |
| Member | In billing, your label (member_id) for a person inside a customer. | Members, teams and agents |
| Outcome | A result you charge for, such as a resolved ticket. It is reported by an event and defined by an outcome definition. | Outcome settlement |
| Outcome charge | A charge that depends on a result. It moves through pending, disputed, confirmed, locked and reversed. | Outcome settlement |
| Outcome definition | The event that reports an outcome, the criteria, the two clocks and the reversal rules. It is versioned. | Outcome settlement |
| Payment provider | The service that collects money for you, such as Stripe, Adyen or Airwallex. Runledger works with several at once and never moves money itself. An Admin confirms the first live one. | Payment providers |
| Plan | What a customer pays and gets: billing mode, currency, interval, rates, pools and allowances. Pricing locks once a customer subscribes. | Prepaid and postpaid billing |
| Pool | A named part of a customer’s prepaid balance, with its own rules for expiry and cost to draw. A plan lists its pools in drawdown order. | Pools |
| Preset | A recommended pair of clocks for a kind of outcome, such as support_chat. The stored definition always holds explicit values. | Outcome settlement |
| Price rule | How the price of a usage event is worked out: cost plus a markup, a table, or a formula. A plan rate points at one. | Price rules and margin guardrails |
| Proposal | A live configuration change an agent suggests. Nothing changes until a signed-in Admin approves the diff. A Collaborator’s live change is a proposal too. | Configuration |
| Rate | The price on a plan for one usage event or one outcome: credits_per_unit on prepaid, unit_amount_decimal on postpaid. | Prepaid and postpaid billing |
| Rate card | One version of a cost model’s rates, with the date it takes effect. | Catalog, cost models and overrides |
| Reference | Your ID for a piece of work, such as a conversation. Later events carrying the same reference find the same outcome charge. | Outcome settlement |
| Reversal | A record that an outcome charge no longer stands, with its source, its reason and its effect on money. | Outcome settlement |
| Reversal horizon | How long after confirmation a charge can still be reversed. When it closes, the charge locks. | Outcome settlement |
| Reversal rule | A rule on an outcome definition that reverses or disputes a charge when a named signal event arrives. | Outcome settlement |
| Run | One agent run, grouped by run_id across check(), track() and trace(), so revenue, cost and margin read together. | Cost attribution and margin |
| Sandbox | The environment where nothing moves money and a coding agent may write. Sandbox keys start with rl_sk_test_ or rl_rk_test_. | Sandbox and test clocks |
| Scope | A permission carried by a restricted key or an OAuth session, such as config:read. A customer session carries separate customer_view. scopes. | Access, actors and audit |
| Settlement | Deciding whether an outcome charge stands. It doesn’t mean money reaching a bank account. | Outcome settlement |
| Signal | An event that reports something about an earlier outcome, such as a customer coming back. A reversal rule can act on it. | Outcome settlement |
| Simulation | A replay of recorded events and costs against a candidate change, with the margin it would have had. | Provider price changes and simulation |
| Spend limit | A cap on the money value of what a customer, team, member, agent or pool consumes in a period. | Spend limits |
| Subscription | A customer’s enrollment on a plan. A customer has at most one active subscription. | Prepaid and postpaid billing |
| Team | In billing, your label (team_id) for a team inside a customer. It is a flat label, not a hierarchy. | Members, teams and agents |
| Test clock | A frozen clock that you move forward, so a month of settlement runs in a few seconds. Sandbox only. | Sandbox and test clocks |
| Thin event | A webhook that names the object that changed and carries no state. You fetch the object. | Webhooks |
| Usage summary | One API read of every window, pool, spend figure and limit that applies to a customer. The guide calls it usage meters. | Usage meters |
| Usage window | The period a refill or cap applies to: fixed, session or sliding. | Usage windows |
| Webhook endpoint | A URL you register to receive events, with the event types you handle. | Webhooks |
Words that look alike
| Pair | Difference |
|---|---|
| Pool and credit type | A credit type is the unit. A pool is a part of the balance in that unit, with its own rules. Most plans that need “included first, then bought” want pools |
| Charge and invoice | A charge is one outcome or usage amount. An invoice collects a postpaid customer’s confirmed charges for a period |
| Hold and outcome charge | A hold reserves an amount before work. An outcome charge is created after the work, and a hold can become it |
| Margin below floor and margin below guardrail | The same guardrail seen two ways. margin_below_floor is the denial reason on a check(). margin_below_guardrail is the warning code on a track() |
| Sandbox and test mode | The sandbox is the environment. A payment provider’s test mode is how that provider is connected there |
| Usage summary and usage meters | The usage summary is the API read. Usage meters is what you show customers from it |
| Customer session and customer view | The session is the API object you create. The view is the hosted page it opens |
Next steps
- How Runledger fits together shows how these parts connect.
- Conventions lists ID prefixes, money, time and list rules.