# Billing and usage

Show where the subscription stands, what has been used against each limit, and what a change of plan would take away.

For: Account owners and admins.

Web page: https://candor.themethodic.com/screens/billing-and-usage

## Layouts

### Plan, seats and meters

Pick it when: The default: the subscription on top, what has been used below it.

Layout: The subscription status across the top; usage meters and a spend chart beneath.

Items:

- **Subscription status** (`subscription-status`, Pro; https://candor.themethodic.com/docs/subscription-status.md): Plan, seats paid against seats used, the card on file, and when it renews or ends.
- **Usage meters** (`usage-meters`, Pro; https://candor.themethodic.com/docs/usage-meters.md): What's used against each limit: seats, an environment's daily API allowance, agent work.
- **Spend breakdown** (`spend-breakdown`, Pro; https://candor.themethodic.com/docs/spend-breakdown.md): AI spend over time, split by model, agent or feature.
- **Stat card** (`stat-card`, Pro; https://candor.themethodic.com/docs/stat-card.md): One metric with its change against a named period.

```bash
npx candor-ui add subscription-status usage-meters spend-breakdown stat-card
```

### Choose a plan, see the cost of leaving one

Pick it when: The person is changing plan or seats.

Layout: Plans side by side; confirming a smaller one opens a dialog listing what is lost and the new total.

Items:

- **Plan picker** (`plan-picker`, Pro; https://candor.themethodic.com/docs/plan-picker.md): Choose a plan and seats.
- **Downgrade impact** (`downgrade-impact`, Pro; https://candor.themethodic.com/docs/downgrade-impact.md): What a smaller plan takes away, the new monthly total and when it takes effect.
- **Alert dialog** (`alert-dialog`, Pro; https://candor.themethodic.com/docs/alert-dialog.md): A dialog that stops for a decision.

```bash
npx candor-ui add plan-picker downgrade-impact alert-dialog
```

### A limit reached inside the app

Pick it when: The person meets a limit while working and needs to know which one and when it resets.

Layout: A notice above the composer naming the limit; the run control stays and says why it can't be used.

Items:

- **Service notice** (`service-notice`, Pro; https://candor.themethodic.com/docs/service-notice.md): A notice about the service itself: a usage limit, a model that's down.
- **Usage meters** (`usage-meters`, Pro; https://candor.themethodic.com/docs/usage-meters.md): The meter behind the notice.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): Run stays and says which limit it is and when it resets.

```bash
npx candor-ui add service-notice usage-meters locked
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): A meter whose figure isn't known says so; it isn't drawn as zero.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Moving to a smaller plan lists what is lost, what happens to what used it, and the date it takes effect.
- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): The plan picker doesn't start on the paid plan; the person chooses.

## Patterns that cover part of it

- Agent cost guard: estimates, budgets and spend: https://candor.themethodic.com/patterns/agent-cost-guard.md

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build billing and usage with Candor UI.
SubscriptionStatus is the top: plan, seats paid against used, the card on file and the renewal or end date.
UsageMeters shows used against each limit. Where a figure is unknown, say so; don't draw an empty bar.
SpendBreakdown splits AI spend by model, agent or feature, from the service's own figures.
PlanPicker chooses plan and seats and starts with nothing chosen. Before a smaller plan is confirmed, DowngradeImpact says what is lost and the new total.
At a limit, put a ServiceNotice above the composer and keep Run in Locked, naming the limit and its reset.
Candor draws the screens. Taking payment and the card itself stay with your billing provider.

Start from the "Plan, seats and meters" layout: The subscription status across the top; usage meters and a spend chart beneath.
Candor items: subscription-status (https://candor.themethodic.com/docs/subscription-status.md), usage-meters (https://candor.themethodic.com/docs/usage-meters.md), spend-breakdown (https://candor.themethodic.com/docs/spend-breakdown.md), stat-card (https://candor.themethodic.com/docs/stat-card.md).
Install: npx candor-ui add subscription-status usage-meters spend-breakdown stat-card
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```