# Billing Settings

> The plan and billing page of an app's settings: current plan with seats and renewal, Change plan, and a Cancel that confirms inline. Usage meters hatch toward where the period is heading and estimate overage past the limit. The card on file warns as it nears expiry, the billing contact edits in place, and invoices carry status badges, downloads and Retry on a failed charge.

- Slug: `billing-settings`
- Category: [Settings](https://www.assembli.design/category/settings.md)
- Type: component
- Tags: settings, billing, subscription, usage, invoices, payment-method, plan, saas
- npm dependencies: lucide-react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/billing-settings
- Page: https://www.assembli.design/components/billing-settings

![Billing Settings preview](https://www.assembli.design/thumbnails/billing-settings-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `plan` (required) | `BillingPlan` |  |  |
| `usage` | `UsageMeter[]` | `[]` |  |
| `period` | `{ start: string; end: string }` |  | ISO dates of the current billing period, for the usage header and its countdown. |
| `paymentMethod` | `PaymentMethod \| null` |  |  |
| `contact` | `BillingContact` |  |  |
| `invoices` | `Invoice[]` | `[]` |  |
| `invoiceLimit` | `number` | `5` | Invoices shown before "Show all". |
| `currency` | `string` | `"USD"` |  |
| `locale` | `string` | `"en-US"` |  |
| `now` | `string` |  | Today, as an ISO date, for expiry warnings and countdowns. Defaults to the visitor's clock after hydration. |
| `title` | `React.ReactNode` | `"Plan & billing"` |  |
| `description` | `React.ReactNode` | `"Manage your subscription, usage and invoices."` |  |
| `onChangePlan` | `() => void` |  |  |
| `onCancelPlan` | `() => Promise<void> \| void` |  | May be async. The plan then shows as canceling until the renewal date. |
| `onResumePlan` | `() => Promise<void> \| void` |  |  |
| `onUpdatePaymentMethod` | `() => Promise<void> \| void` |  |  |
| `onContactChange` | `(contact: BillingContact) => Promise<void> \| void` |  |  |
| `onRetryInvoice` | `(invoice: Invoice) => Promise<void> \| void` |  | Retry a failed charge. Resolving marks the invoice paid. |
| `onDownloadInvoice` | `(invoice: Invoice) => void` |  |  |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/billing-settings/billing-settings.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/billing-settings
```

Registry item JSON: https://www.assembli.design/r/billing-settings.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.