Arr waterfall

ARR waterfall

Turns "MRR by customer by month" into the ARR bridge finance teams and boards expect. The math is done by a script, so the numbers are repeatable and tie out every month.

Inputs

Ask for one CSV, saved as data/subscriptions.csv:

• month (2026-09 or 2026-09-01), customer_id, and either mrr or arr.
• One row per customer per month while they pay. Several rows for one customer in a month (several subscriptions) are added together.
• Months a customer is missing count as zero ARR.

Where to get it: a billing system "MRR by customer" report, a revenue schedule from the books, or a spreadsheet with one column per month (reshape it to long format first and tell the user you did).

If the user only has a list of subscriptions with start and end dates, build the monthly rows first (one row per active month, amount normalized to monthly) and show them five sample rows before running.

Steps

1. Check the file. Read the header and 10 rows. Confirm: which column is the amount, MRR or ARR, currency (one currency only; if several, ask for converted amounts), and whether amounts include one-time fees (they should not; ask to remove setup and services fees).

2. Run the script.

   node scripts/arr-waterfall.mjs data/subscriptions.csv --out out/arr-waterfall

   Options: --from 2026-01 and --to 2026-09 to limit the range.

3. Read the outputs in out/: arr-waterfall.md (summary), arr-waterfall.csv (one row per month, for a spreadsheet), arr-waterfall.json, and arr-waterfall-movements.csv (every customer movement, so any number can be traced).
4. Sanity check before sharing. The script confirms each month ties out. Also look for: a single customer driving most of a month's churn or expansion, a jump that looks like a data issue (a customer at 10x their usual amount), and reactivations that are really a renamed customer ID.
5. Write the summary for the user using the template below. Lead with ending ARR and net new ARR, then the driver that moved most.

Definitions (state these when sharing)

• New: first month a customer ever has ARR.
• Reactivation: a customer who had ARR before, went to zero, and came back.
• Expansion / contraction: change in ARR for a customer active in both months.
• Churn: a customer active last month with zero this month. Full amount counts as churn.
• NRR (monthly): (starting + expansion - contraction - churn) / starting. New and reactivation are excluded.
• GRR (monthly): (starting - contraction - churn) / starting.
• Cohort NRR / GRR: customers active in the first month, their ARR in the last month over their ARR in the first. GRR caps each customer at their starting ARR. With 13+ months the script also reports trailing 12-month NRR and GRR, the number most investors mean by "NRR".

Output template

## ARR, <first month> to <last month>
Ending ARR: $X (net new $Y, +Z% over the period)
Driver: <the biggest movement in one sentence>

| Month | Starting | New | Expansion | Contraction | Churn | Ending | NRR |
...

Watch: <1 to 3 customers or patterns worth a look>

Guardrails

• Never edit the user's source file. Reshaped or cleaned data goes in a new file in data/ with a clear name.
• Do not mix bookings, billings, and recognized revenue. If the user is not sure what the export contains, ask before presenting the numbers as ARR.
• If the script skips rows, say how many and why. Stop and ask if more than 2% of rows were skipped.
• Customer names are business data: summarize, do not paste the full movements file into chat.

ARR waterfall

Turns a monthly MRR or ARR export into the ARR bridge your board expects: starting ARR, new, reactivation, expansion, contraction, churn, and ending ARR, with NRR and GRR. Every month ties out, and every number traces back to a customer in the movements file.

Who it is for: founders, finance leads, and RevOps folks who build the ARR slide by hand each month.

Example

Input (examples/subscriptions.csv, 10 customers over 6 months):

month,customer_id,plan,mrr
2026-04,acme-co,growth,2000
2026-04,bluebird-labs,growth,1500

Output (out/arr-waterfall.md):

Starting ARR $153,600 | New $51,600 | Reactivation $8,400 | Expansion $14,400 | Contraction -$8,400 | Churn -$36,000 | Ending ARR $183,600
Cohort retention, customers active in 2026-04, measured in 2026-09: NRR 84.4%, GRR 75.0%.

Plus a month-by-month table, out/arr-waterfall.csv for your spreadsheet, and out/arr-waterfall-movements.csv with every customer movement.

What it can access

• Runs node scripts/arr-waterfall.mjs (Node built-ins only, no packages).
• Reads your export from data/. Writes only out/arr-waterfall* files.
• No network, no API keys.

Setup

None. Export MRR by customer by month to data/subscriptions.csv and ask Claude for an ARR waterfall.