subscriptions.churn

export function churnMetrics(customersAtStart: number, customersLost: number, mrrAtStart: Money, expansionMrr: Money, contractionMrr: Money, churnedMrr: Money): ChurnMetrics

/** Rates in basis points (10000 is 100%), rounded half-up; null when the period started with nothing to measure against. */
export interface ChurnMetrics {
  /** customersLost / customersAtStart */
  readonly logoChurnBasisPoints: number | null;
  /** (contraction + churned) / mrrAtStart */
  readonly grossRevenueChurnBasisPoints: number | null;
  /** (contraction + churned - expansion) / mrrAtStart; negative when expansion wins */
  readonly netRevenueChurnBasisPoints: number | null;
  /** (mrrAtStart - contraction - churned) / mrrAtStart */
  readonly grossRevenueRetentionBasisPoints: number | null;
  /** (mrrAtStart + expansion - contraction - churned) / mrrAtStart */
  readonly netRevenueRetentionBasisPoints: number | null;
}

import { churnMetrics } from "#fune/subscriptions.churn@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, assertSameCurrency } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type ChurnMetrics } from "./subscriptions_churn_types.ts";

function rate(numerator: number, denominator: number): number | null {
  return denominator === 0 ? null : roundDiv(numerator * 10000, denominator, "half-up");
}

/**
 * Logo churn, gross and net revenue churn, and gross and net revenue
 * retention for one period, each as basis points of the starting cohort.
 */
export function churnMetrics(
  customersAtStart: number,
  customersLost: number,
  mrrAtStart: Money,
  expansionMrr: Money,
  contractionMrr: Money,
  churnedMrr: Money,
): ChurnMetrics {
  if (!Number.isInteger(customersAtStart) || customersAtStart < 0 || !Number.isInteger(customersLost) || customersLost < 0) {
    throw new RangeError(`customer counts must be whole numbers of 0 or more, received ${customersAtStart} and ${customersLost}`);
  }
  if (customersLost > customersAtStart) {
    throw new RangeError(`customers lost must not exceed customers at start, received ${customersLost} of ${customersAtStart}`);
  }
  for (const amount of [expansionMrr, contractionMrr, churnedMrr]) assertSameCurrency(mrrAtStart, amount);
  const start = mrrAtStart.minor;
  const expansion = expansionMrr.minor;
  const lost = contractionMrr.minor + churnedMrr.minor;
  if (start < 0 || expansion < 0 || contractionMrr.minor < 0 || churnedMrr.minor < 0) {
    throw new RangeError("MRR amounts must not be negative");
  }
  if (lost > start) {
    throw new RangeError(`contraction and churned MRR must not exceed MRR at start, received ${lost} of ${start}`);
  }
  return {
    logoChurnBasisPoints: rate(customersLost, customersAtStart),
    grossRevenueChurnBasisPoints: rate(lost, start),
    netRevenueChurnBasisPoints: rate(lost - expansion, start),
    grossRevenueRetentionBasisPoints: rate(start - lost, start),
    netRevenueRetentionBasisPoints: rate(start + expansion - lost, start),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add subscriptions.churn

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./subscriptions.churn-1.0.0-typescript.fune, or fetch it from a terminal with fune pull subscriptions.churn@1.0.0:typescript.

The whole function, every language, is one file too: subscriptions.churn-1.0.0.fune, 19,176 bytes, sha256 2de1c509adb029c3c9ebed57f1d3285cc2bbcaa850afc64282e4384e7ceb12a6. It installs into a project of any language.

// fune: before subscriptions.churn

// fune: after subscriptions.churn

// fune: replace math.round-div in subscriptions.churn
// fune: replace money.amount in subscriptions.churn

// fune: step subscriptions.churn after <n|label>

More from the author

These are ChartMogul's published definitions (Gross MRR Churn Rate, Net MRR Churn Rate and Net Revenue Retention), which are the ones most SaaS reporting uses. Net revenue churn goes negative when expansion from existing customers outweighs what they took away ("negative churn"), and net revenue retention goes above 10000 (100%) in the same case. ChartMogul adds reactivation MRR to expansion in NRR and net churn; if you want the same, pass expansion plus reactivation as `expansionMrr`.

Every input is about the cohort at the start of the period. New customers who joined during it, and the MRR they brought, are left out: they are growth, not retention, and including them is the most common way churn gets under-reported. A customer who joined and cancelled within the period is not in `customersLost` either.

Each rate is one exact division rounded half-up (away from zero for a negative net churn) to a whole basis point, so 1 lost out of 3 is 3333 (33.33%). A rate is null rather than an error when its denominator is zero: a business with no customers at the start of the month has no churn rate, not a churn rate of zero.

Errors: negative counts or amounts, more customers lost than there were, more MRR contracted and churned than there was, and amounts in different currencies.

Sources: ChartMogul, "Revenue churn (net and gross revenue churn rate)", https://chartmogul.com/saas-metrics/revenue-churn/ and "Net Revenue Retention (NRR)", https://chartmogul.com/saas-metrics/nrr/.

Files