> 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.

# 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](/guides/usage-summary).

## Before you start

* The [usage summary](/guides/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`.

**`POST /v1/customer_sessions`**

```json title="POST /v1/customer_sessions"
{
  "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"
}
```

**`Response: CustomerSession`**

```json title="Response: CustomerSession"
{
  "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](/api-reference/how-configuration-works), and override any field for one session with `branding` on the session request.

**`Config document: customer view branding`**

```json title="Config document: customer view branding"
{
  "account_settings": {
    "customer_view_branding": {
      "name": "Acme",
      "logo_url": "https://app.example.com/logo.png",
      "accent_color": "#17614f"
    }
  }
}
```

**`POST /v1/customer_sessions`**

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

| Field          | Value                                                                                 |
| -------------- | ------------------------------------------------------------------------------------- |
| `name`         | The name at the top of the page, up to 80 characters. Defaults to your account's name |
| `logo_url`     | An `https` URL for your logo. The page loads the image from there                     |
| `accent_color` | A six-digit hex color, such as `#17614f`, for buttons and links                       |

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](/api-reference/access-and-audit#keys-and-scopes).

| Scope                       | The customer can                                                                                                                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer_view.usage`       | See their meters, pool balances, credits that expire next, spend limits and invoices                                                                                                                      |
| `customer_view.checkout`    | Buy credits, through [checkout](/concepts/billing#checkout) at your payment provider. The credits expire after one year unless your plan sets another length, as with any [top-up](/guides/credit-expiry) |
| `customer_view.spend_limit` | Set, lower or remove their own [spend limit](/guides/spend-limits), up to its ceiling                                                                                                                     |
| `customer_view.auto_top_up` | Set or turn off their [auto top-up](/guides/auto-top-up-and-alerts), within the plan's bounds                                                                                                             |

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](/api-reference/test-in-the-sandbox) customer it shows the clock's time.

## When it fails

| Result                          | Cause                                                           |
| ------------------------------- | --------------------------------------------------------------- |
| `403` with `insufficient_scope` | The key lacks `customer_sessions:write`                         |
| `403`                           | The key is an agent key. Agent keys can't create sessions       |
| `404` with `resource_not_found` | No customer has that ID                                         |
| `400` with `parameter_invalid`  | A scope outside the four above, or an `expires_in` over `PT24H` |

[Idempotency and errors](/reference/idempotency-and-errors) lists every code.

## API reference

[Create a customer session](/api-reference/customer-sessions/create).

## Next steps

* [Usage meters](/guides/usage-summary) is the API read behind the page.
* [Spend limits](/guides/spend-limits) and [auto top-up](/guides/auto-top-up-and-alerts) are what customers can change.
* [Going live](/going-live/overview) lists what to check before real billing starts.