> 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. # The dashboard > **Note** > > The dashboard is for you and your team. Your end customers don't see it. They get the [customer view](/guides/customer-view), a hosted page that you open for them with a one-time link. The dashboard shows what the API did and lets the right person act on it. It adds nothing the API lacks: every screen reads and writes through the same endpoints, so a person, a script and an agent get the same result and the same errors. ## Sandbox first A new account opens in the sandbox, on a **Get started** page that takes you, or the coding agent working for you, from nothing to a first outcome charge and then through the going-live checklist. [Creating an account](#create-an-account) gives you a sandbox and live keys and live configuration from the start; live takes no payments until the checklist passes and Runledger has reviewed the account. A **Sandbox | Live** switch sits in the top bar, and the address contains the environment, so a link never points at the wrong one. The page offers two paths: * **With an agent.** A connect command for your coding agent, a scoped key to give it, a setup prompt that names the MCP tools in order, and a feed of what the agent has done so far. * **By hand.** Templates for the objects you need, code snippets, and a panel that waits for your first event. The going-live checklist is the same one as in [Going live](/going-live/overview). Rows the data can show, such as "a live endpoint responds 2xx", tick themselves, and the rest you attest. The first row is a verified email address, and the last is **Reviewed by Runledger**. ## What's in it | Group | Screens | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Home | Overview: revenue by state, disputes due, the reversal rate and its reasons, the rates by outcome definition, reconciliation, webhook health, and the latest five changes agents made. Top-up chargeback numbers are on Payment providers | | Outcomes | Charges, Disputes, Reversals, Outcome definitions | | Customers | Customers, with balances by pool, usage windows, spend limits, auto top-up, grants, holds, the ledger, and whether the saved payment method is usable. Holds, every customer's in one list | | Billing and revenue | Plans and credit types, Subscriptions, Spend limits, Invoices, Revenue, Breakage, Reconciliation (per provider), Exports, Runs and margin | | Pricing | Provider catalog, Cost models, Rate cards, Price rules, Margin guardrails, Simulations | | Developers | Get started, API keys and agent access, Config export and import, Request logs, Events, Webhooks, Test clocks (sandbox only) | | Settings | Account, Payment providers, Team and roles, Notifications, Alerts, Customer view, Audit log | The group is called **Outcomes**, not Settlement. In payments, "settlement" usually means money reaching a bank account, which Runledger never touches, and the API's objects are outcome charges, outcome definitions and disputes. [Outcome settlement](/concepts/outcome-settlement) keeps the term for the concept. Two screens carry most of the day-to-day work: * **Charge detail** tells one charge's whole story: the event that created it, the definition version and its clocks, each status change and its cause, which rules matched, any dispute and its deadline, the reversal and its effect on the invoice or balance. * **Disputes** is a decision queue, soonest deadline first, with the evidence beside the decide button and what happens if nobody decides. Money is shown by state (pending, confirmed, reversed) and never adds credits to currency or one currency to another. **Plans and credit types** shows each plan's top-up settings, including how long purchased credits last: one year unless the plan sets another length. A customer's grants show the `expires_at` of each. **Config export and import** downloads the configuration as one JSON file, with its `hash`, and imports one. Import has two modes. **Add and update**, the default, matches objects by key and removes nothing. **Replace** makes each section the file carries exactly what it lists, removing the objects missing from it, and leaves a section the file leaves out untouched; it is refused if the configuration changed since you opened the screen. The screen checks the file first and lists every change field by field, each removal included, before anything can be applied. Into the sandbox it applies at once. Into live it creates a proposal, which shows as **Pending approval** until an Admin accepts it. See [how configuration works](/api-reference/how-configuration-works#validate-then-apply). **Price changes** isn't a nav item. It opens from the banner on Cost models and Price rules, and from the price changes link on Provider catalog. A catalog price change is reviewed in four steps: what changed, what it touches, simulate first, and decide for each price rule: hold (the default), follow, or reprice (a new version of the rule from its start date onward). Costs already recorded keep their rates and are never repriced. An Admin decides in live, and a Collaborator can review it and propose the decision. A Collaborator's hold on a rule already on hold is recorded at once, since it changes no price. Holding a price change writes a `catalog.price_change_held` [audit event](/api-reference/access-and-audit#the-audit-log) with the person as actor and the price change ID, and the review shows who chose what and when. A decided rule has **Decide again**, so there is no separate un-hold: choosing follow or reprice is an ordinary price rule change and is audited as one. See [price changes](/guides/price-changes-and-simulation#decide-what-happens-to-your-prices). **Exports** lists every export in the environment, newest first, however it was created: in the dashboard, with `POST /v1/exports`, or by an agent. Each row shows what was exported, its status, its source (`dashboard`, `api` or `agent`) and when it was created, and a download link when it is ready; the file is kept for seven days, after which the export shows as `expired`. The same list is `GET /v1/exports`, with `limit` and `cursor` ([list exports](/api-reference/exports/list)). Creating an export needs the role in the table below. **Runs and margin** lists runs with their revenue, cost and margin, filtered by customer, outcome definition, time range and whether a run has a margin. A run has a margin only with a confirmed charge and a traced cost, so a run with only pending or reversed charges shows none. A totals row above the list adds up revenue, cost and margin across every run that matches the filters, not only the runs on the page, and it is `GET /v1/runs/summary` ([summarize runs](/api-reference/runs/summary)). Only runs with a margin add to those totals. The row shows how many matching runs have none and were left out, and it is one currency at a time. **Charts** draw three reports: revenue by state on Revenue, breakage on Breakage, and top-up chargebacks on Payment providers. Each reads the same report you can call with the API, so the chart, the totals and the list agree. Runs and margin shows cost by model for the runs on screen, summed from `GET /v1/costs`. [Reports and charts](/guides/reports) covers every report the API serves, charted or not. **Customer view** opens the hosted page for one customer: pick the customer and tick the scopes, and the screen shows the link once, with a preview of what the customer will see, read from their usage summary. The link opens once, in the first browser that opens it, so open it yourself or give it to the customer, not both. See [the customer view](/guides/customer-view). ## One configuration, three surfaces Outcome definitions, plans (with their allowances, pools and default spend limit), credit types, webhook endpoints, payment providers, routing rules, notification rules, operator spend limits and the grant expiry notice can all be changed in the dashboard, with the API, or by an agent. [Cost models, price rules and margin guardrails](/concepts/cost-reflective-pricing) follow the same pattern. Each form has **Preview changes**, which is the [dry run](/api-reference/how-configuration-works#dry-run), and shows the same warnings an agent gets. Each config screen has a **History** link to the [audit log](/api-reference/access-and-audit#the-audit-log) filtered to that object, and shows who last changed it, including which agent. A live change an agent proposes appears as **Pending approval**, and so does a live change a Collaborator makes in the dashboard. An Admin reads the diff, then approves or rejects it, and the approver and time are recorded as `approved_by` in the [audit log](/api-reference/access-and-audit#the-audit-log). ## Create an account Anyone can sign up at the dashboard with an email address and a password, or with Google. Sign-up asks you to accept the Terms and the Privacy Policy, and asks nothing else: there is no question about how you found Runledger. It creates a sandbox and nothing more. Live is not part of sign-up. * **No verification to start.** You land in the sandbox straight away. You don't have to verify your email to see your sandbox key or to use the sandbox. Verifying is the first row of the going-live checklist, and live can't open until it is done. * **Your first key.** A new Admin lands on **Get started**. The sandbox key is created when you press the button: a restricted key, starting `rl_rk_test_`, with every scope but `charges:write` and `disputes:resolve`, no expiry and no spend cap, shown once, so copy it before you leave the page. Confirming or reversing a charge by hand and deciding a dispute need a secret key from API keys. Roll or revoke it any time on the API keys screen. * **Payments in live are a separate step.** Live keys and live changes work before the review. Live takes no payments until every row of the going-live checklist passes and Runledger has reviewed the account. The review is manual, and an Admin asks for it once every other row is done. While it runs, the checklist reads **In review by Runledger**. Once it is approved, an Admin connects and confirms the first live payment provider, which is the last step; connecting a live provider isn't open yet. See [Going live](/going-live/overview). * **Set up with us.** If Runledger sets up your account with you, we create it and send your first Admin the usual invite link. ## Sign in You sign in with an email address and a password, with Google, or with a magic link. A magic link is an emailed link that signs you in, and it is valid for 15 minutes. It opens a "Check your email" page, with **Resend**. **Forgot password** emails a link. The link is valid for 1 hour and works once, and resetting your password signs out every other session. Two-factor sign-in is optional for everyone, in an Admin's account and a Collaborator's alike, and nothing makes it a condition of going live. Turn it on from **Account**: add an authenticator app (you scan a setup key, enter a six-digit code, and save your recovery codes, which are shown once) or a passkey. You can remove either one. Text-message codes aren't offered. ## Your team An Admin invites people from **Team and roles**. The invite names an email address and a role, [Admin or Collaborator](#roles), and Runledger emails that address a link. * **The link** is valid for 7 days. **Resend invite** starts the 7 days again, and **Revoke invite** withdraws it. * **Accepting** means signing in, or signing up, with the address that was invited. The person doesn't have to verify their email first, and skips the first-run steps. They land on the team's Overview with the role chosen at the invite. * **Size.** A team holds up to 10 people, with pending invites counted. The invite screen shows how many places are used, such as "8 of 10". At 10, **Send invite** is off and **Request more** asks Runledger to raise the limit. * **Admins.** A team can have several Admins. The last Admin can't be demoted or removed, so a team is never left without one. * **Support.** When Runledger support acts in your account, a banner runs across the top of every screen, and what support does is recorded in the [audit log](/api-reference/access-and-audit#the-audit-log) as Runledger support. Support can't reveal an existing secret key, which is shown once when it is created or rolled, and can't confirm a live payment provider. ## Roles Runledger has two roles, and you choose one for each person when you invite them. Both read everything, in the sandbox and in live. An **Admin** runs the account: the team, live keys, payment providers, going live and billing configuration, and decisions on proposals. A **Collaborator** does the day-to-day work (customers, plans, usage, invoices, holds, sandbox keys and reports) and proposes live changes for an Admin to approve. A team can have several Admins. | Capability | Admin | Collaborator | | -------------------------------------------------------------- | ----- | ----------------------------- | | View all data, sandbox and live | Yes | Yes | | Create and roll sandbox keys | Yes | Yes | | Create live restricted keys | Yes | No | | Create live secret keys | Yes | No | | Create, scope and revoke agent keys | Yes | Sandbox only | | Edit configuration in the sandbox | Yes | Yes | | Edit live configuration | Yes | Proposes the change | | Approve or reject a proposal | Yes | No | | Connect payment providers and set routing | Yes | No | | Remove a live payment provider | Yes | No | | Confirm the first live payment provider | Yes | No | | Request the going-live review | Yes | No | | Confirm early, reverse, open or decide a dispute | Yes | Yes | | Extend or release a hold | Yes | Yes | | Decide a catalog price change (hold, follow or reprice) | Yes | Proposes the decision in live | | Reset the sandbox | Yes | No | | Grant and void credits | Yes | Yes | | Set, raise or remove one customer's spend limit or auto top-up | Yes | Yes | | Open a customer view for a customer | Yes | Yes | | Run a simulation | Yes | Yes | | Use **Try it** on the Price rules screen | Yes | Yes | | Create exports and act on invoices | Yes | Yes | | Manage notification rules and the customer view's branding | Yes | No | | Invite people, change roles and remove people | Yes | No | | Turn on two-factor sign-in for yourself | Yes | Yes | A control a role can't use is off, with a note saying who can. Either role can run a [simulation](/guides/price-changes-and-simulation) of a price or cost change against recorded events, on the Simulations screen in the Pricing group. A simulation records itself and changes no balance, invoice or live configuration, so it isn't a configuration edit. Through the API a simulation needs `config:read` and `events:read`. Plan allowances, pools and a plan's default spend limit are configuration, so the two configuration rows apply to them: in live an Admin changes them directly, and a Collaborator's change is a proposal. A live operator spend limit that isn't for one customer is a proposal from everyone, an Admin included, and the Spend limits screen can't delete one in live, since a removal has no proposal there; change it through the [configuration document](/api-reference/how-configuration-works) instead. An Admin can approve any proposal, including one that changes routing rules or notification rules, although only an Admin edits those directly. A single customer's spend limit or auto top-up is customer data, like a credit grant, so either role changes it. When a customer changes their own limit or top-up in the [customer view](/guides/customer-view), the change is recorded as actor `system` named `customer_session`, and no role is involved. Extending or releasing a hold in the dashboard is open to either role. An extension is in whole days, from one day to 30. Changing a customer's auto top-up writes an `auto_top_up` [audit event](/api-reference/access-and-audit#the-audit-log) with the actor. Your own backend and agents extend and release holds through `POST /v1/holds/{id}/extend` and `/release`, with their own scopes. The first live payment provider is confirmed by an Admin, after a successful test payment with that provider in the sandbox. Until then it takes no payments. An agent can start the connection and can't confirm it, and neither can a Collaborator. Agents are not a role. They act through keys or OAuth sessions with [scopes](/api-reference/access-and-audit#keys-and-scopes). Sign-up, sign-in, the team and roles belong to the dashboard and aren't part of the public API. ## Next steps * [Configuration](/api-reference/how-configuration-works) describes the document the dashboard edits. * [Access, actors and audit](/api-reference/access-and-audit) covers keys, scopes and the audit log. * [Set up with a coding agent](/agents/mcp) lets a coding agent do the same setup.