Stripe billing — programme plan

Living document: update the status columns, the decision log and the change log in the same commit as the work they describe. Status legend: ✅ done · 🟡 in progress · ⬜ planned · 🚫 dropped · ❓ blocked on a decision.

1. Goal

An installation is owned by one company and exposes several applications. It uses one Stripe token (one Stripe account), configured through the environment exactly like the other providers (Google, GitHub, …) — see D2. Two billing mechanics coexist, deliberately (D1):

1. Prepaid credit wallet (already shipped, see the LiteLLM gateway & credit wallet plan) — the user tops up a euro balance and spends it across applications. This is the multi-application token-usage mechanic, metered by the LiteLLM gateway.
2. Paid subscription (this programme) — a paid product plan opens access on month N; its metered features are billed at the end of the billing period, i.e. month N+1. This is the per-product mechanic.

An application can delegate the whole billing surface to auth-service (subscription, invoices, usage) through the server-rendered templates mechanism, or present the billing itself by calling auth-service: it reports billable usage through a callback and reads a user's subscription, consumption and invoices through an API scoped to its own application.

Operator and user never touch the Stripe dashboard: the admin interface creates, updates and deletes the Stripe objects (products, prices, meters, subscriptions) and the user pays on Stripe's own Checkout / Billing Portal pages (D4).

2. Architecture

                 admin UI                          user (profile / app page)
                    │                                        │
             plans + prices + meters                 subscribe / invoices / usage
                    ▼                                        ▼
   ┌────────────────────────────── auth-service ──────────────────────────────┐
   │  services/billing/  ── Stripe API ──►  Products · Prices · Meters          │
   │        ▲                                Customers · Subscriptions         │
   │        │                                Invoices · Checkout · Portal       │
   │        │                                                                  │
   │  subscription_plan_prices (fixed | metered)                               │
   │  user_subscriptions (+ stripe_subscription_id, status, period)            │
   │  billing_customers · billing_usage_* · stripe_invoices (cache)            │
   └───────────────▲───────────────────────────▲──────────────────────────────┘
                   │ webhook (invoice.*, subscription.*)     │ usage callback
                   │                                        │ (POST /api/consumption, metered key)
              Stripe webhooks                         application backend

• auth-service is the source of truth for entitlements (features claim, user_subscriptions) and for the catalogue (which feature is metered, its unit, its price, its hard cap).
• Stripe is the source of truth for money for subscriptions: it aggregates the reported usage and issues the invoice at the end of the period.
• The wallet stays separate: it is not a Stripe subscription. Its top-ups remain a Stripe Checkout in payment mode.

3. Data model (frozen)

This model is frozen here (D3). It is applied incrementally, each table/column landing in the same PR as the code that first uses it: until the first production deploy the consolidated 0000_initial_schema.sql baseline is regenerated from src/db/schema.ts (AGENTS.md §8), so there is no delta migration to write. The "introduced in" column names the lot that first adds it.

Plan features JSON. With D3 frozen as "prices are the source of truth", metered definitions move out of the plan features JSON into subscription_plan_prices. The JSON keeps only static feature flags, so the token features claim carries entitlements (booleans, quotas) and never a mutable usage counter. A metered feature's cap and price are read from the prices table, not the claim.

4. Decisions

5. Programme overview

A lot is done only when pnpm build:server, pnpm lint, pnpm format:check, pnpm test and pnpm test:integration pass.

6. Lot details

Lot 0 — Foundations (✅)

Lot 1 — Webhook rewrite (✅)

Lot 2 — Customer & catalogue sync (✅)

Notes (2.1–2.3): catalogue logic lives in src/services/billing/catalog.ts (no Stripe calls in the routes); the plan price CRUD moved to src/routes/admin/plan-prices.ts with shared schemas/helpers in src/routes/admin/plan-shared.ts. A meter is shared per (application, feature key) so usage aggregates once per customer regardless of the plan; it is deactivated when its last price is removed. A fixed price cannot carry metered fields, a metered price cannot be one-off, and the feature_key charset matches the consumption keys ([A-Za-z0-9.]). Deleting a plan now also removes its inactive subscriptions — the Lot 1 webhook keeps cancelled subscriptions, which the RESTRICT FK would otherwise block. Amount, currency, interval and feature_key are immutable (a change archives the Stripe price and creates a new row); only name/unit/cap are updatable. Tasks 2.4–2.7 were delivered afterwards (see the change log).

Pre-test audit (2026-10-27) found three gaps in this lot, all closed by 2.6 and 2.7:

• the default free plan created with an application is inserted directly and does not create a Stripe Product (provisionPlanProduct is only called from the plan-create route), so a new application starts without a catalogue;
• getOrCreateBillingCustomer is implemented and tested but has no call site, so no Stripe Customer is created yet;
• renaming an application does not rename its plans' Stripe Products, and deleting an application does not archive its plans' Products, archive their Prices or deactivate their Meters (only deleting a plan does).

Lot 3 — Subscription lifecycle (✅)

Notes: every plan, the default free one included, is backed by a Stripe subscription. A plan with no price at all gets a 0 EUR monthly Price on first assignment (and its Product if missing), so the free subscription can exist and metered features on it can bill. The sync runs from the assignment paths (admin grant, default plan, self-service) and never from setUserSubscription, which is the webhook target — so a Stripe event cannot loop back into a Stripe call. It is best-effort: a failure is logged and the local entitlement stays authoritative; pnpm billing:reconcile links the missing subscriptions.

Lot 4 — Metered billing (✅)

Notes: the per-period aggregate is authoritative for the cap; Stripe only invoices at period end. The period is the UTC calendar month (billing_period_start), not the Stripe subscription period — the cap is our concern, the invoice is Stripe's. The event insert comes first in the transaction so a retry cannot double-count; an over-cap report rolls back both the event and the increment. The push is an outbox (stripe_meter_event_identifier stays null until Stripe accepts it), drained by pnpm billing:reconcile and a background retry every five minutes. Covered by src/tests/billing-metered.integration.test.ts.

Lot 5 — Invoices & application read API (✅)

Notes: the cache is written by every invoice.* event before the entitlement logic runs, so a wallet top-up receipt (no subscription) is cached too. Owner: the Stripe Customer through billing_customers, then the userId metadata. Application: the local subscription row, then the applicationId metadata (a row may not exist yet when the first invoice arrives). Each row keeps last_event_at; an update applies only when the event is not older (Stripe does not deliver in order). The application API takes the application from the client_credentials token (azp) and scopes every query to it; it needs the billing:read machine scope, granted by a superadmin. Wallet top-up receipts are never exposed through it. The profile's invoice history is Lot 7.1.

Lot 6 — Delegated pages (Eta) (✅)

Notes: the pages are server-rendered from the same data services as the application API, and every figure is formatted in the visitor's language. The subscribe actions are POSTs issued by a small script inside the page (the session cookie is sent; Fastify does not parse form posts, so no <form> method). Links from Stripe are rendered only over https://.

Lot 7 — Frontend

Notes. Before the UI, a review of the webhook path found that a superseded subscription (a free one still active after a paid checkout) could rewrite the entitlement of the paid one, through its update, deletion and invoices. The fix is in the webhook service: an event is applied only when it concerns the subscription linked to the (user, application) row, or when no link exists yet. A checkout completion links the new subscription first and cancels the free one afterwards. Covered by src/tests/billing-subscription-changes.integration.test.ts, whose guard tests fail when the guard is disabled (checked by mutation). The profile's billing card now shows the real invoices and the usage of the current period; the estimate and its placeholder are removed. Frontend has no component-test tooling: the panel is verified by vue-tsc, the production build, and the server-side tests of the data it shows.

Lot 8 — Hardening (✅)

7. Open questions

8. Risks

• auth-service on the payment critical path: Stripe meters and subscriptions must tolerate retries; every mutation carries an idempotency key.
• Two money models (wallet EUR vs Stripe subscription): keep them visibly separate in the UI and in the ledger; never debit the wallet for a subscription or bill Stripe for wallet token usage.
• Meter lag: our billing_usage_periods aggregate is authoritative for the hard cap; Stripe's summaries are only for invoicing, so a cap decision never waits on a Stripe round-trip.
• Delegated pages: fail-closed, and never render card fields (Stripe handles payment, D4).

9. Change log