Revenue metrics: the contract
Every revenue number Bucker returns names the definition it was computed under. The definitions
are data, published as versioned files with a sha256 and an effective date, in
@bucker/shared/analytics/metric-contracts:
| File | Defines |
|---|---|
revenue-v1.json |
MRR, ARR, the MRR bridge, active customers, customer and revenue churn, ARPU, LTV, gross revenue, refunds, fees, net revenue, deferred revenue, and the currency policy |
web-v1.json |
pageviews, visitors, sessions, bounce rate, conversion rate |
A published contract is immutable. Changing a word changes its sha256, which a test pins, so a
change is a new file (revenue-v2.json) with a new effective date. Every read states the contract
name, version and sha256 beside its figures. A contract is exportable in MetricFlow's
semantic-model shape (toSemanticModelYaml); a converter for other formats is not built.
The definitions that are easy to get wrong
MRR is each account's recurring charge normalised to one month (annual / 12, quarterly / 3), net of recurring discounts, excluding tax, one-off charges and usage overage. ARR is 12 x MRR.
The bridge splits a month's change in MRR, per account, into five movements:
start + new + expansion + reactivation - contraction - churn = endnewis an account with no MRR ever before;reactivationone that had MRR earlier, none at the start of the month and some at the end. The identity is checked for every month in integer minor units and a residual other than zero is refused with an error naming the month, never rounded.Churn is a rate of accounts (customers lost over customers at the start) or of revenue ((churn + contraction) over start MRR). Both are null when the start is empty, not zero.
LTV is ARPU divided by customer churn. It is null below 30 customers at the start of the month and null at zero churn; a number there would be believed and is noise or infinity.
Net revenue is gross minus refunds minus fees. A source that reports no fees yields
feesKnown: false, not a zero fee.Currency. Amounts convert at the rate of the day they occurred and the rate version used is stored. An amount with no rate for its day is excluded and counted (
unconvertible, with the currencies), never read as zero.
Reading it
readMrrBridge (domain/src/modules/web/revenue/bridge.ts) reads account_revenue_days and returns
at most 24 months, each with its identity checked, plus an optional breakdown by plan and the
unconvertible count. It is aggregate-only: no account key leaves it. It is an end-user read, so
it refuses with analytics_not_enabled (422) and touches no table while the project's PA-01 gate is
shut. A month's opening and closing figures are snapshots: the latest row on or before the month
boundary, so an account the daily rollup did not touch keeps its last known MRR, and a churn is a row
with zero MRR. The running month's end is the day of the read and is marked closed: false.
What is and is not stored
Stored: keyed pseudonyms of the paying account and subject, a hashed vendor customer reference, amounts in minor units with currency, the base-currency amount and the rate version, product and plan ids, service period, timestamps. Not stored: a name, an email, an address, a card number, last four digits or brand, or any raw vendor identifier. A test scans the revenue tables' columns for these.