06.15
Billing and entitlements
Executive summary
Billing runs subscriptions through Stripe, a credit wallet with an append-only ledger, and a usage ledger whose unit is a documented encounter (ADR 0020). AI spend is capped per clinic per month and enforced in the request chain before any model is called. Purchases are refused inside the native apps by design.
Overview
- ProductionOperate · Billing and entitlementsCharge for value delivered — a documented encounter — and make AI cost predictable for the clinic and for the platform.
Pipeline
- Stripe checkout and the customer portal manage subscriptions; signed webhooks update state.
- Documented encounters are recorded in a usage ledger and settled per period by a scheduled worker.
- The AI chain enforces the plan token allowance and a monthly USD cap per clinic before the model call.
- Entitlements decide which modules a clinic can use.
Data owned
- Subscriptions and entitlements
- Holds
- Plan and module access
- Credit wallet and credit ledger
- Holds
- Balance and append-only movements
- Documented-encounter usage ledger and periods
- Holds
- The billing unit and its settlement
| Store | Holds |
|---|---|
| Subscriptions and entitlements | Plan and module access |
| Credit wallet and credit ledger | Balance and append-only movements |
| Documented-encounter usage ledger and periods | The billing unit and its settlement |
Models and engines
This module makes no model calls. Everything it computes is deterministic code.
Guardrails
- The ledger is append-only.
- Cost caps can only be lowered by override, never raised.
- Native builds cannot reach checkout.
Rollout and status
- ProductionSubscriptions, usage ledger, AI cost capsEnforced in the AI gate chain
- ShadowPer-call credit pricingCost map computed and recorded, not charged
Interfaces
- Consumes
- What
- Documented encounters
- Consumes
- What
- AI decision log (token and cost)
- Emits
- What
- Entitlements
- Emits
- What
- Budget refusals (HTTP 429)
| Direction | What |
|---|---|
| Consumes | Documented encounters |
| Consumes | AI decision log (token and cost) |
| Emits | Entitlements |
| Emits | Budget refusals (HTTP 429) |
SOURCE OF TRUTH
server/services/billing/server/routes/billing.tsserver/services/aiCostBudget.tsdocs/adr/0020-documented-encounter-billing-unit.md