Skip to content
bucker

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 = end

    new is an account with no MRR ever before; reactivation one 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.