Billing, Metering, and Payments Service implemented
This page is the detailed engineering packet for the money-domain shared services.
Scope
The shared money domain owns:
- usage ingestion and attribution
- rating inputs and pricing context
- immutable ledger entries
- balances and billing posture
- checkout sessions, webhooks, refunds, and provider reconciliation
It should not be reimplemented inside each product.
Control Model
Main Invariants
| Invariant | Why it matters |
|---|---|
| ledger is append-only | money truth must not be rewritten |
| balances are derived, not directly mutated | prevents hidden financial drift |
| attribution includes organization / department / project | one shared billing model across products |
| payment reconciliation is auditable | provider custody must remain reviewable |
Attribution Shape
Billing should preserve:
- organization id
- department id
- project id
- billing account id
- actor / service account id
- product id
- resource type and resource id
- usage unit and quantity
- pricing snapshot
Main Contract Surfaces
| Surface | Purpose |
|---|---|
| usage ingest API/events | record billable usage inputs |
| billing read models | show balance, usage, financial posture |
| payment session APIs | checkout/initiation path |
| webhook worker | provider event handling and reconciliation |
| finance recovery / audit surfaces | operator-safe money correction path |
Failure / Recovery Model
| Failure class | Expected posture |
|---|---|
| usage ingest delayed | buffer durably and surface lag |
| payment webhook delayed | retry durably |
| ledger writer unhealthy | fail safely; never silently skip writes |
| stale balance read | show freshness / posture explicitly |
Security / Audit Expectations
- no direct ledger mutation
- all privileged finance actions audited
- payment custody and refund paths are evidence-bearing workflows
- repeated direct SQL checks indicate missing operator read surfaces