# Billing settings

A shadcn/ui billing page for SaaS apps: plan, card on file, billing details and invoices, with a payment methods dialog for cards, a backup card and wallets.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available for the docs, pricing and about pages: append `.md` to the URL or send an `Accept: text/markdown` header (the home page answers the header too). An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## At a glance

- **Good for:** Billing pages for SaaS and AI apps on a subscription; Managing saved cards, a backup card and wallets in one place; Account pages with invoices and billing details; Admin dashboards with a sidebar and a settings area
- **Category:** Billing & payments › Payment methods, Billing & payments › Invoices, Billing & payments › Plans · **Type:** Settings, Forms, Tables · **Style:** Motion, Minimal, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/blocks/billing-settings) · [Screenshot](https://www.craftui.space/llms.md/preview/billing-settings.cf28b137.jpg)

![Billing settings](https://www.craftui.space/llms.md/preview/billing-settings.cf28b137.jpg)

## Install

```bash
pnpm dlx shadcn@latest add https://www.craftui.space/r/billing-settings.json
```

This is a paid item (BLK-SGBAYA): the install needs a craftUI plan or a purchase of it. Signed in, the docs page gives your personal install command. Plans: https://www.craftui.space/pricing

## Usage

```tsx
import BillingSettings from "@/components/blocks/billing-settings/billing-settings";

export default function Page() {
  return <BillingSettings />;
}
```

With no props it renders with demo content; pass your own through the props below.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shell` | `Partial<Omit<AppShellProps, "children">>` | — | The app around the page: brand, sidebar links, the person. |
| `plan` | `BillingPlan` | `built-in demo value` | The current plan and its next invoice. |
| `cards` | `CardBook` | `built-in demo value` | Saved cards, the default one and the backup. |
| `wallets` | `WalletState` | `built-in demo value` | Wallets already connected (the account), or null. |
| `billing` | `BillingInfo` | `DEMO_BILLING` | What prints on every invoice. |
| `invoices` | `Invoice[]` | `built-in demo content` | Recent invoices, newest first. |
| `actions` | `Partial<BillingActions>` | — | Your server calls; anything left out uses the demo. |
| `onChangePlan` | `() => void` | — | Opens your plan picker. |
| `onViewAllInvoices` | `() => void` | — | Opens your full invoice list. |
| `className` | `string` | — | Height and placement of the app, e.g. "h-dvh" or "h-[46rem]". |

### `AppShellProps`

| Field | Type | Description |
| --- | --- | --- |
| `brand` (required) | `string` | Product name next to the monogram, e.g. "Acme". |
| `brandColor` (required) | `string` | Background of the brand monogram, any CSS colour. |
| `groups` (required) | `ShellGroup[]` | The sidebar's link groups. |
| `active` (required) | `string` | Id of the current sidebar link. |
| `trail` (required) | `string[]` | Where the page sits, e.g. ["Settings", "Billing"]. |
| `title` (required) | `string` | The page heading, e.g. "Billing". |
| `description` (required) | `string` | One line under the heading. |
| `actions` | `React.ReactNode` | Buttons at the right of the page header. |
| `user` (required) | `{ name: string; email: string }` | The signed-in person, shown at the foot of the sidebar. |
| `children` (required) | `React.ReactNode` | The page itself. |
| `className` | `string` | Height and placement, e.g. "h-dvh" (the default) or "h-[46rem]". |

### `BillingPlan`

| Field | Type | Description |
| --- | --- | --- |
| `name` (required) | `string` | Plan name, e.g. "Pro". |
| `price` (required) | `number` | Price per interval, in dollars. |
| `interval` (required) | `"month" \| "year"` | Billed each month or each year. |
| `seats` (required) | `number` | Seats on the plan. |
| `renewsOn` (required) | `string` | When it renews, as you want it shown, e.g. "Dec 1, 2026". |
| `nextInvoice` (required) | `number` | The next invoice's total, in dollars. |
| `status` (required) | `"active" \| "past_due" \| "canceled"` | "active" shows a green pill; "past_due" an amber one. |

### `CardBook`

| Field | Type | Description |
| --- | --- | --- |
| `cards` (required) | `SavedCard[]` | Up to four saved cards, in the order they show. |
| `defaultId` (required) | `string` | Id of the card that's charged. |
| `backupId` (required) | `string \| null` | Id of the card tried when the default fails, or null. |

### `BillingInfo`

| Field | Type | Description |
| --- | --- | --- |
| `email` (required) | `string` | Where receipts go. |
| `company` (required) | `string` | Company name printed on invoices. |
| `street` (required) | `string` | Street address. |
| `city` (required) | `string` | City and postcode, e.g. "San Francisco, CA 94105". |
| `country` (required) | `string` | Country name. |
| `taxId` (required) | `string` | VAT or tax number; empty shows "None added". |

### `Invoice`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Shown as the invoice number, e.g. "#1042". |
| `date` (required) | `string` | As you want it shown, e.g. "Nov 1, 2026". |
| `description` (required) | `string` | What it was for, e.g. "Pro, 10 seats". |
| `amount` (required) | `number` | In dollars. |
| `status` (required) | `"paid" \| "open" \| "failed" \| "refunded"` | Shown as a pill: Paid, Open, Failed or Refunded. |

### `BillingActions`

| Field | Type | Description |
| --- | --- | --- |
| `saveCards` (required) | `(book: CardBook) => Promise<void>` | Save the cards, the default and the backup (the dialog's Save). |
| `verifyCard` (required) | `(card: NewCard) => Promise<void>` | Check a new card with the bank (3-D Secure) and save it. Reject to decline. |
| `retryCard` (required) | `(card: SavedCard) => Promise<Partial<SavedCard>>` | Retry a declined card. Return new details if the bank sent any, or {}. |
| `saveBilling` (required) | `(info: BillingInfo) => Promise<void>` | Save the billing details printed on invoices. |
| `downloadInvoice` (required) | `(id: string) => Promise<void>` | Download one invoice. |
| `connectWallet` (required) | `(id: WalletId) => Promise<string>` | Connect a wallet; resolve with the account it connected as. |
| `disconnectWallet` (required) | `(id: WalletId) => Promise<void>` | Disconnect a wallet. |

### `ShellGroup`

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` | Small heading above the group; leave out for none. |
| `items` (required) | `ShellLink[]` | The links in the group, in order. |

### `SavedCard`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Your id for the card (e.g. the payment provider's). |
| `brand` (required) | `CardBrand` | "visa", "mastercard" or "amex": picks the logo. |
| `last4` (required) | `string` | The last four digits. |
| `expires` (required) | `string` | MM/YY |
| `name` (required) | `string` | Name on the card. |
| `nickname` | `string` | A label you give it, e.g. "Company card". |
| `addedBy` (required) | `string` | Who added it, shown in the card editor. |
| `addedOn` (required) | `string` | When it was added, as you want it shown. |
| `declinedOn` | `string` | The last charge failed on this date. |
| `updatedByBank` | `boolean` | The bank sent new details (card account updater). |

### `NewCard`

| Field | Type | Description |
| --- | --- | --- |
| `brand` (required) | `CardBrand` | Detected from the first digits. |
| `number` (required) | `string` | All digits, no spaces. Send it to your payment provider, not your server. |
| `expires` (required) | `string` | MM/YY |
| `cvc` (required) | `string` | The 3 or 4 digit security code. |
| `postcode` (required) | `string` | Billing postcode. |

### `ShellLink`

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique id; matched against `active` to mark the current page. |
| `label` (required) | `string` | Text in the sidebar, e.g. "Billing". |
| `icon` (required) | `IconSvgElement` | A Hugeicons icon from `@hugeicons/core-free-icons`. |

## Files

The install adds:

- `components/blocks/billing-settings/billing-settings.tsx`
- `components/blocks/billing-settings/app-shell.tsx`
- `components/blocks/billing-settings/payment-methods-dialog.tsx`
- `components/blocks/billing-settings/card-slot.tsx`
- `components/blocks/billing-settings/card-editor.tsx`
- `components/blocks/billing-settings/add-card-form.tsx`
- `components/blocks/billing-settings/wallets.tsx`
- `components/blocks/billing-settings/billing-details.tsx`
- `components/blocks/billing-settings/undo-toast.tsx`
- `components/blocks/billing-settings/brand-marks.tsx`
- `components/blocks/billing-settings/status-button.tsx`
- `components/blocks/billing-settings/odometer.tsx`
- `components/blocks/billing-settings/ui.tsx`
- `components/blocks/billing-settings/actions.tsx`
- `components/blocks/billing-settings/use-card-draft.ts`
- `components/blocks/billing-settings/card-data.ts`
- `components/blocks/billing-settings/billing-motion.ts`
- `components/blocks/billing-settings/surface.ts`

npm dependencies (installed for you): `@hugeicons/core-free-icons`, `@hugeicons/react`, `motion`, `@base-ui/react`, `react-use-measure`.

shadcn/ui components it uses (the shadcn CLI adds any that are missing): `button`, `dialog`, `input`, `label`, `sheet`, `switch`, `tabs`, `tooltip`.