Customer view

The customer view is a Runledger-hosted page for one of your customers. It shows their usage meters and balances, and lets them buy credits and set their own limits. It carries your account’s name, not Runledger’s. You open it with a one-time link from your backend and don’t build anything unless you want your own design. For that, read the same data from the usage summary.

Before you start

• The usage summary, which the page shows.
• A key that can create sessions, with the scopes you want the customer to have. Agent keys can’t create sessions.

It isn’t the dashboard. The dashboard is for your team. The customer view is for your end customers, and it shows one customer’s data and nothing else.

Open it

Create a session from your backend when the customer opens your billing screen, then redirect them to url.

{
  "external_customer_id": "org_123",
  "scopes": ["customer_view.usage", "customer_view.checkout", "customer_view.spend_limit", "customer_view.auto_top_up"],
  "return_url": "https://app.example.com/billing",
  "expires_in": "PT1H"
}

{
  "id": "csess_2mV6bQ9rKd",
  "object": "customer_session",
  "customer": "cus_9sF2kq81LmQz",
  "scopes": ["customer_view.usage", "customer_view.checkout", "customer_view.spend_limit", "customer_view.auto_top_up"],
  "url": "https://billing.runledger.co/s/csess_2mV6bQ9rKd",
  "return_url": "https://app.example.com/billing",
  "branding": { "name": "Acme", "accent_color": "#17614f" },
  "expires_at": "2026-11-04T14:12:09Z",
  "livemode": false,
  "created_at": "2026-11-04T13:12:09Z"
}

The link works for that customer and those scopes until expires_at, which is PT1H by default and at most PT24H. It isn’t an API key, and it opens once: the browser that opens it first keeps the page and its forms, through a cookie, until expires_at. The same link opened anywhere else shows a page that says it has been used and sends the customer back to return_url, and so does a link that has expired. Create the session when the customer opens your billing screen and redirect them to the url. Don’t email it: a mail scanner that follows links would open it first and use it up. Treat the url as a secret until it is used, and never put an API key in a browser.

Creating a session needs customer_sessions:write, which is granted one key at a time. Agent keys can’t create sessions.

Brand the page

The page can carry your logo, name and accent color. Set the default for every session once, in the account settings of your configuration, and override any field for one session with branding on the session request.

{
  "account_settings": {
    "customer_view_branding": {
      "name": "Acme",
      "logo_url": "https://app.example.com/logo.png",
      "accent_color": "#17614f"
    }
  }
}

{
  "external_customer_id": "org_123",
  "scopes": ["customer_view.usage"],
  "return_url": "https://app.example.com/billing",
  "branding": { "name": "Acme Support", "accent_color": "#0b57d0" }
}

Every field is optional. A field a session leaves out takes the account default, and the CustomerSession response returns the branding the page uses.

What a customer can do

Each scope opens one part of the page. Grant only what your product lets customers do.

These are customer view scopes, a separate list from API key scopes.

A customer can only tighten what you set. They can’t raise a limit above its ceiling, and the page doesn’t offer to. The same rules apply as for the API, because the page calls it. The limit a customer sets on the page covers them as a whole and blocks, with no alert_at. Buy credits shows only on a prepaid plan that sells top-ups, and the auto top-up form only once the customer has a saved card; buying credits on the page doesn’t save one.

Records and events

A change the customer makes is recorded as actor system named customer_session, with the session’s ID, so the audit log and each limit show that it came from the page. Spend limit changes send spend_limit.updated. Setting, changing or turning off an auto top-up sends no webhook, and turning it off removes the rule. The purchases a rule makes later send auto_top_up.succeeded or auto_top_up.failed, and a rule that stops by itself after three failed payments sends auto_top_up.disabled. Purchases show up as normal checkout sessions and payments.

Sandbox

A session created with a sandbox key opens a sandbox page, marked as a test, and with a test clock customer it shows the clock’s time.

When it fails

Idempotency and errors lists every code.

API reference

Create a customer session.

Next steps

• Usage meters is the API read behind the page.
• Spend limits and auto top-up are what customers can change.
• Going live lists what to check before real billing starts.