Billing

The billing settings page of a SaaS product. It shows the current plan and the card it's charged to, usage meters for metered limits, the plans on offer with a monthly/yearly switch, billing details, invoices and a way to cancel. Every action waits on your own async callback, shows busy while it runs, and says what went wrong if it fails.

Each subscription state changes the whole screen, not just a badge. A trial shows the days left. Past due shows a red banner with the grace period and Update payment method. A plan that's canceled shows when access ends and offers Keep subscription; once it has ended, Resubscribe. If the subscription needs something done, the banner at the top says what.

<Billing  subscription={subscription} // { planId, interval, status, seats, periodStart, periodEnd, … }  plans={plans}               // cheapest first  usage={usage}               // [{ id, label, used, limit, resetsAt, atLimit }]  paymentMethod={card}        // { brand, last4, expMonth, expYear, failure? } or null  invoices={invoices}  details={details}  currency="USD"  onChangePlan={(planId, interval) => api.post("/billing/plan", { planId, interval }).then(refresh)}  onUpdatePayment={() => stripe.openCardForm().then(refresh)}  onSaveDetails={(next) => api.put("/billing/details", next).then(refresh)}  onCancel={(reason, note) => api.post("/billing/cancel", { reason, note }).then(refresh)}  onResume={() => api.post("/billing/resume").then(refresh)}/>

When to use it

• The billing page of a product that charges per seat or a flat price per month or year, with optional metered limits (AI credits, messages, storage).
• As the page itself, or with sections cut away: leave out usage, invoices, details or paymentMethod and that part goes.

When not to

• Checkout for a first purchase. That's a focused flow with one plan and a card form, not a settings page.
• Usage analytics: charts over time, cost per project. Link to them from here; the meters only answer "how close am I to the limit".
• The card form itself. onUpdatePayment should open your processor's form or portal (Stripe Elements, a hosted page) rather than collect card numbers here.

States

Changing plans

plans is in order, cheapest first, and the order decides what's an upgrade. The monthly/yearly switch shows each plan's price for that period as a monthly figure ("$15 per seat / month") with the total for the subscription's seats under it. "Save 17%" is the largest yearly saving across the plans, worked out from price.month * 12 against price.year.

Due today is an estimate. For the same interval it's the difference in price times the days left over the days in the period. For a switch to yearly it's a full year less the unused part of this period. The dialog says the invoice has the exact amount. If your processor can preview proration, its number is better: put it in the plan's description or fork DialogBody in plans.tsx.

What's lost is every line of the current plan's features that the new plan doesn't have, word for word. Write features so that a lower tier's line differs ("2,000 AI credits a month" against "10,000 AI credits a month"), and the downgrade lists exactly what goes.

Props

Every callback can return a promise. The block shows busy until it settles and shows the rejection's message if it fails. It never changes data itself: resolve after your state reflects the change, and the screen follows from the props.

Customizing

• Plan names and features come from your pricing page. Keep features short and parallel across tiers; they double as the downgrade's loss list.
• atLimit on each meter is your product's real consequence ("Copper stops drafting menus and replies until then."), not "Limit exceeded".
• cancelNotes: say what stops and what's kept, and for how long.
• The cancel reasons are in REASONS in billing.tsx. Keep them to six or fewer, in your customers' words.
• The grace period and retry wording comes from graceUntil and nextRetry; leave them out if your processor doesn't retry.
• Spacing reads the shared roles: --ui-gap-section between sections (48 narrow, 56 from 600px), --ui-gap-block between cards, --ui-gap-group under a section's heading, and --ui-pad-card inside every card.
• Widths: the cards sit side by side once the block is 720px wide (so the payment card fits its button), and invoices fold into two-line rows at 520px. Both are container queries, so the block lays out right in a narrow settings column.
• Edges: every card's outline is the field edge color (--ui-edge, in --ui-shadow-resting), so the cards and the buttons in them read as one set; lines inside a card are the lighter --ui-border. The plan you're on takes the selected edge (--ui-field-focus), still one hairline.

Accessibility

• One heading at headingLevel, each section a <section> named by its heading, plan names one level further down.
• Usage bars are role="meter" with "7,420 of 10,000 credits used" as their value text, named by the label and described by the line under them.
• The billing period switch is a radio group named "Billing period". The plans are a list named by the section heading, each item named by its plan.
• The invoices are a real <table> with column headers; the download column's header is visually hidden. Each link reads "Download invoice LRD-2026-0140, October 14, 2026, PDF". On a phone, the header row is visually hidden but stays readable.
• A polite role="status" region announces each change once it lands: "Acme Business, billed monthly, starts now.", "Billing details saved.", "Subscription canceled. You keep Acme Team until November 14, 2026."
• Banners use the Alert component and are there from the start, so they're read in page order, not interrupting. A change that makes one appear, like canceling, is announced in the status region instead.
• The plan dialog takes focus on its first button. The cancel dialog is an alert dialog with focus on Keep subscription, so the safe choice is the default. After a cancel, the button that opened it is gone, and focus goes to the page title. Typing a note and then pressing Escape asks before throwing it away.
• Editing details moves focus to the first field. Escape or Cancel brings it back to Edit details. Validation runs on blur and on save, focuses the first wrong field, and says how to fix it.
• Compare plans scrolls to the plans (no smooth scroll under reduced motion) and moves focus to their heading.
• Buttons are the standard 40px; download links reach 40px under a finger.

Before / after

Before: a status string, a price, and a button that goes to the processor's portal for everything else. Nobody knows the credits are about to run out until Copper stops.

<div>  <h1>Billing</h1>  <p>Plan: team ({sub.status})</p>  <p>${sub.amount / 100}/mo</p>  <a href={portalUrl}>Manage billing</a></div>

After: the plan, its price and renewal in words; a meter that warns at 80% and says what to do at 100%; plan changes that state the charge today and what a downgrade loses; and a banner whenever something needs doing.

<Billing  subscription={sub}  plans={plans}  usage={usage}  paymentMethod={card}  invoices={invoices}  details={details}  onChangePlan={changePlan}  onUpdatePayment={openCardForm}  onSaveDetails={saveDetails}  onCancel={cancel}  onResume={resume}/>