Billing

Business billing uses Stripe as the billing/invoicing engine and Vendure as the canonical ledger. The full architecture + decision log lives in docs/business-billing-architecture-plan.md; this page is the orientation.

Key ideas

• Billing mode — none (unconfigured), a_la_carte (per-usage), or contract (fixed rate). Set at provisioning; changeable by admin.
• Billing status — active, past_due, restricted. Driven by Stripe webhooks + billing scanner cron.
• Collection method — applies only to contract mode: subscription (recurring Stripe sub), prepaid (upfront), or external (invoiced outside Stripe).
• Invoice mirror — local cache in billing_invoice_mirror, updated by webhooks. Audit trail in business_billing_audit.
• Money gate — live, money-moving actions (e.g. domain purchase) are gated by a runtime admin toggle (platform_config.domains_purchase_enabled), not an env var.
• Catalog sync — Stripe products/prices are synced from code on boot (modules/billing/stripe-catalog-sync.ts).

Billing status state machine

stateDiagram-v2
    [*] --> active : provisioned
    active --> past_due : Stripe payment fails
    past_due --> active : payment retried successfully
    past_due --> restricted : grace period expires (default 7 days)
    active --> restricted : contract ends with restrict action
    restricted --> active : admin re-activates

See Billing types for the full mode/status/collection-method reference.

Code

• apps/scheduler-api/src/modules/billing/ — billing-scanner, billing-gate, admin-billing routes, Stripe catalog sync.
• Operator procedure: Stripe account cache runbook.

See the Billing flow for the runtime sequence.