Billing
The Billing page — the plan catalog, tenant subscriptions, invoices, revenue lines, and dunning. What's wired to a real store, what's derived, and where the Stripe checkout path fits in.
Billing
The Billing page is the operator's money view: the plan catalog, every
tenant's subscription and MRR, the invoice ledger, revenue by line, and a dunning
banner. It's gated by the profitability.view privilege — without it the
page shows a locked state ("You need the profitability.view privilege to see
billing.").
Everything on this page is built so the numbers reconcile with Tenants and Profitability: MRR is derived from one plan catalog, so no figure here is hand-entered.
What's real vs. derived vs. stub
Billing spans a few layers with different levels of wiring. Being precise about this matters:
| Piece | State |
|---|---|
| Plan catalog | Real, static — the single source of pricing (lib/billing/plans.ts) |
| Subscriptions + MRR | Derived live from tenants × the catalog — not stored |
| Invoices | Real, persisted store (Postgres when DATABASE_URL is set, else a seeded in-memory mock). "Send statement" on Tenants writes a real open invoice here |
| Revenue by line | Read from the profitability data source |
| Dunning banner | Real, but derived — it lists the invoices already in past_due; it doesn't itself send emails from this page |
| Stripe checkout | Wired as an API endpoint (below), not a button on this page |
A badge by the title reads persisted or demo data for the invoice
store. On demo data the invoices shown are the seed set.
The plan catalog
The catalog is the one source of pricing, keyed by tier. Each tenant's MRR is computed from its tier here:
| Plan | Monthly | Included servers | Included seats | Per-server overage |
|---|---|---|---|---|
| Solo | $29 | 1 | 1 | $19 |
| Team | $99 | 3 | 5 | $25 |
| Business (popular) | $349 | 10 | 10 | $29 |
| MSP · White-label | $1,290 | 50 | 50 | $19 |
| Enterprise | Custom | — | — | contract |
A tenant's MRR is monthly + (servers − includedServers) × perServerOverage,
but only while the tenant is billable (active or past-due). Trials and
churned tenants contribute 0, and Enterprise is contract-priced (shown as
"contract", excluded from self-serve MRR).
KPIs, subscriptions, and invoices
The KPI row shows MRR (derived) with a paying-subscription count, Paid this month, Open amount, and Past due (which flips to a dunning trend when non-zero). Each amount is summed straight from the invoice store by status.
The Subscriptions table lists every non-churned tenant on its plan, with its status, server count, and derived MRR — sorted by MRR. The Invoices table lists every invoice newest-first (id, tenant, amount, status, issued, due), with past-due rows highlighted. Revenue by line renders the profitability revenue lines as bars, with a resold-VPS margin called out in the section hint.
Dunning
When any invoices are past due, a red Dunning banner appears listing each
overdue invoice (tenant, id, due date) and notes that "dunning reminders sent;
license enters grace on continued non-payment." This banner reflects the
past_due invoices in the store — it's the operator's at-a-glance dunning view,
not a send button. The actual license consequence (a failed payment moving a
license toward grace) is handled by the Stripe event path below, and the customer
sees the grace/expiry transitions described in
the customer licensing view.
Stripe checkout (API path)
Self-serve checkout is wired as a dependency-free Stripe integration
(lib/billing/stripe.ts) exposed at POST /api/v1/billing/checkout — not as
a control on this page. The design choice is deliberate: HostSSH talks to
Stripe's HTTP API directly rather than pulling in the Stripe SDK, and verifies
webhooks against the exact raw body bytes.
- Checkout session. The endpoint is agent-gated (an agent presents its
license key), derives the license id from that key, and creates a Stripe
Checkout subscription session for the requested self-serve tier
(solo/team/business/msp — Enterprise is contract-only). It returns a
sessionIdand hostedurl. - Configuration. It needs
STRIPE_SECRET_KEYand a per-tier price id env var (STRIPE_PRICE_SOLO,…_TEAM,…_BUSINESS,…_MSP). If those aren't set the endpoint returns a 503 with the missing-config message — so on an unconfigured/dev instance, checkout is effectively a stub until the keys are provided. - Webhook effects. Verified Stripe events map onto license state: a completed checkout / created / updated subscription sets the license active (and its tier); a failed invoice payment moves it to grace; a deleted subscription moves it to suspended. These state changes only persist when a database is configured.
Related
- Where subscriptions and statements originate → Tenants
- The license states Stripe events drive → Licensing (admin) and the customer view