Billing: UI Spec

Scheme

The Billing page for each customer type, in the UI Scheme notation: a line is a text block, a frame is a widget, widgets in one frame share a row.

Contracting	Pay/Go	Metered
/dashboard/billing/ billing-intro billing-banner credit-balance alerts billing-history	/dashboard/billing/ billing-intro billing-banner credit-balance alerts auto-top-up billing-history	/dashboard/billing/ billing-intro billing-banner included-credits alerts billing-history

Layout

Page states

Each state links to the prototype in that state. The widget title stays in every state. Tags, banners and the balance card buttons are hidden while loading or on error.

State	Rendering
Loading	`m__skeleton` in the shape of the content. Balance: one large bar and two rows of small bars. Alerts: two rows with a button. Tables: real headers, four rows of bars. Charts: their own grid, pulsing.
Empty	Balance: 0.00 with the purchase buttons (Metered: full included credits and its rows). Alerts: same rows, “No thresholds yet.” Tables: headers and one centered caption line, no Filter or Export. Charts: axes and grid, no data.
Error	`m__widget__placeholder`: “Couldn’t load data” in caption colour, centered, with `m__button-secondary-outline.S` “Try again”. Tables and charts use the large placeholder.
Page error	One widget instead of all blocks: large placeholder, at least 18rem tall, same text and button.

Modes

Customer type changes the balance card:

Contracting: Used this period, Renews; buttons Buy Credits and Apply Credit Code.
Pay/Go: Used since last top-up, Last top-up; the same two buttons.
Metered: Included credits used, Estimated overage (once used up), Next invoice, Monthly commitment; no buttons.

and the banner:

When	Contracting	Pay/Go	Metered
75% used	Info, Buy Credits	Info, Auto Top-Up Settings	Info, Overage alerts
90% used	Info, Buy Credits	Info, Auto Top-Up Settings	Info, Overage alerts
100% used	Error, Buy Credits	Error, Buy Credits, Turn On Auto Top-Up	Info, Set overage alert
Top-up failed	—	Error, Update Payment Method	—

View-only keeps the layout and the data:

Buttons that change something are removed, not disabled: Edit, Manage, Retry, banner buttons.
In the balance card the buttons are replaced by an xs caption at the card bottom: “Only your organization’s admins can buy credits.”
View, Filter and Export stay.

Components

Design system components on these pages and where each one is used.

Component	Used for
`m__widget`	Every block: balance card, Alerts, Auto Top-Up, Billing History. Usage is one widget: the request table, then both charts.
`m__widget-header` `m__searchbar`	Top line of the Usage widget instead of a title: search by model or API key, with Filter and Export on the right.
`m__alert-error`	Banners. Info (blue) for 75%, 90% and metered billing; error (red) for stopped usage and a failed top-up. No icon.
`m__button-primary.M` `m__button-secondary-outline.M`	Buy Credits and Apply Credit Code in the balance card; Pay in the Buy Credits modal.
`m__button-primary.S`	Main action: Enable Auto Top-Up, the first button of an error banner, Save in modals.
`m__button-secondary-outline.S`	Everything else: Edit, Manage, Retry, Try again, Filter, Export, info banner buttons, Cancel in modals.
`m__menu-button-secondary.S`	View in Billing History, with Invoice and Receipt.
`m__tag`	Status in both tables and the Auto Top-Up state. Success: Paid, Active, On. Error: Failed. Warning: Open. Muted: Used, Expired, Off.
`m__tag-flat`	API key in Usage History.
`m__textfield.M`	All modal fields: thresholds, recipients, credit code, custom amount, Auto Top-Up settings.
`m__select.M`	Threshold type in the Low balance modal: “% used” or “credits left”.
`m__radio-card`	Credit presets in the Buy Credits modal, stacked.
`m__toggle-primary`	Enable Auto Top-Up in its modal.
`m__skeleton`	Loading state of every widget.
`m__widget__placeholder`	Error state of every widget and the page error.
`m__toast`	Confirmation after Save, Apply Code and Retry.