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:

PieceState
Plan catalogReal, static — the single source of pricing (lib/billing/plans.ts)
Subscriptions + MRRDerived live from tenants × the catalog — not stored
InvoicesReal, 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 lineRead from the profitability data source
Dunning bannerReal, but derived — it lists the invoices already in past_due; it doesn't itself send emails from this page
Stripe checkoutWired 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:

PlanMonthlyIncluded serversIncluded seatsPer-server overage
Solo$2911$19
Team$9935$25
Business (popular)$3491010$29
MSP · White-label$1,2905050$19
EnterpriseCustom——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 sessionId and hosted url.
  • Configuration. It needs STRIPE_SECRET_KEY and 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.