Stripe will tell you what MRR is today. The board wants something different: what it was on the first of the month, what it is now, and every pound of movement in between, labelled as new business, expansion, contraction, churn or currency. That movement table is the MRR waterfall, and it is the page most finance directors at a subscription business end up rebuilding by hand each month-end.
This guide shows how to build it from Stripe objects directly: which objects and fields to read, the normalisation rules that turn a price into a monthly figure, how each customer's change gets classified, and where your number will differ from the one in the Stripe Dashboard.
What Stripe already gives you
Start with Stripe's own Billing analytics. It defines MRR as the sum of the monthly-normalised value of all active and past_due subscriptions, leaving out taxes, free-plan subscribers and metered (usage-based) products. A subscription that is canceled or marked unpaid counts as churn. Stripe's own example divides a 600 USD annual plan by 12 to get its monthly contribution.
The same page defines MRR growth as opening MRR plus new, reactivation and expansion MRR, minus contraction and churn MRR, adjusted for foreign exchange. That is the waterfall. Live-mode accounts can also download three prebuilt reports from the Billing overview: MRR per subscriber per month, subscription metrics per month (which includes an MRR roll-forward), and a log of customer MRR changes.
So why build it yourself? Four reasons come up repeatedly:
- The definition is partly configurable and partly not. Stripe lets you choose whether recurring and one-time discounts reduce MRR, but permanent recurring discounts are always subtracted. Its support article on MRR says a subscription set to cancel at period end stops counting at the time of the API call, not when the paid period runs out. Your board may want a different rule, or at least both figures side by side.
- Multi-currency limits. Stripe notes that filtering and grouping the MRR growth chart by product or price is not available if you process subscription volume in multiple currencies.
- Time zones. Prebuilt report dates are in UTC while the charts use your account time zone, so monthly totals might not match exactly, as Stripe itself warns.
- The waterfall rarely lives alone. It feeds a board pack, gets checked against the CRM and the ledger, and needs to be broken down by segment, owner or region that only exist outside Stripe.
The data model
Stripe objects and fields
Every field below appears in Stripe's API reference for that object.
| Object | Fields used | Why |
|---|---|---|
| Subscription | id, customer, status, currency, items, discounts, cancel_at_period_end, cancel_at, canceled_at, ended_at, trial_start, trial_end, pause_collection, start_date |
Whether the subscription is in MRR at the snapshot date, and when it changed |
Subscription item (within items) |
price, quantity, current_period_start, current_period_end |
Seats or units and the price they are billed at |
| Price | unit_amount, currency, type, recurring.interval, recurring.interval_count, recurring.usage_type, tax_behavior, product |
The amount per billing interval and how long that interval is |
| Discount | source.coupon, subscription, subscription_item, start, end |
Which coupon applies, at which level, and until when |
| Coupon | percent_off, amount_off, currency, duration, duration_in_months |
How much comes off, and for how long |
| Invoice | customer, billing_reason, status, total_excluding_tax, period_start, period_end, parent |
A cross-check against what was actually billed |
| Your rate table | currency, month-end date, rate to reporting currency | Stripe amounts arrive in each subscription's own currency; you need a fixed rate per month-end |
Amounts on prices and invoices are integers in the smallest currency unit (pence, cents), so divide by 100 for most currencies before showing them.
Joins
| From | To | Key |
|---|---|---|
| Subscription | Customer | subscription.customer |
| Subscription | Subscription item | subscription.items.data[] (each item also carries subscription) |
| Subscription item | Price | item.price.id, then price.product for the product |
| Subscription or item | Discount | discounts (use expand[]=discounts), or discount.subscription_item |
| Discount | Coupon | discount.source.coupon |
| Customer MRR | Reporting currency | subscription currency + month-end date to your rate table |
| Stripe customer | CRM account | A shared ID you store on both sides, usually in metadata. Don't match on company name |
Normalisation rules
- Recurring licensed items only. Skip prices where
typeisone_timeand items whererecurring.usage_typeis metered; usage revenue gets its own line, not MRR. - Monthly value per item =
unit_amount×quantity÷ months in the interval. A yearly price is ÷ 12; a monthly price withinterval_countof 3 is ÷ 3. Tiered prices have no singleunit_amount, so price those from the tier table or from the last invoice line. - Taxes out. If a price's
tax_behaviorisinclusive, its amount contains tax, so strip it before it enters MRR. - Discounts. Decide once and write it down. The method here subtracts
foreverandrepeatingcoupons while they are active and ignoresoncecoupons, roughly matching Stripe's "subtract recurring discounts" setting. Anamount_offcoupon comes off each invoice, so on an annual price divide it by 12 too. - Status.
activeandpast_duecount.trialing,paused,canceled,unpaid,incompleteandincomplete_expiredcontribute zero. Treat a setpause_collectionas zero as well: Stripe's reference says it leavesstatusunchanged, so a status filter alone will not catch it. - Scheduled cancellations. Pick a rule for
cancel_at_period_end. This guide keeps the subscription in MRR until it actually ends, then reports the scheduled amount separately so you can reconcile to Stripe. - Currency. Convert each customer at the opening month-end rate for every movement, then add one FX line: closing MRR at the closing rate minus closing MRR at the opening rate.
Classifying each customer's movement
Work at customer level, not subscription level, so a customer moving from one subscription to another is a change rather than a churn plus a new.
| Opening MRR | Closing MRR | Movement |
|---|---|---|
| 0, never paid before | > 0 | New |
| 0, paid in an earlier month | > 0 | Reactivation |
| > 0 | higher | Expansion |
| > 0 | lower, still > 0 | Contraction |
| > 0 | 0 | Churn |
The check that keeps the report honest: opening + new + reactivation + expansion − contraction − churn ± FX = closing, to the penny. If it doesn't add up, something has been classified twice or not at all.
Snapshots, not event history
It is tempting to rebuild history from customer.subscription.updated and customer.subscription.deleted events. Stripe's List all events endpoint only goes back 30 days, though, so events cannot rebuild last year. The dependable pattern is a snapshot: read every subscription with its items, prices and discounts at each month-end (daily if you want intra-month views), store it, and compute the waterfall by comparing one stored snapshot with the previous one. Events are still useful for spotting changes as they happen.
Month-end snapshot · October 2026
MRR waterfall from Stripe · Sorrelby Software (fictional)
MRR fell £371 in Oct
to £28,482.
Built from subscriptions, subscription items and prices. Annual and quarterly prices normalised to a month, recurring discounts subtracted, trials and paused subscriptions left out, all in GBP.
- Closing MRR
- £28,482
- Opening £28,853
- ARR (MRR × 12)
- £341,786
- Run-rate, not revenue
- Churn + contraction
- £2,985
- Oct, at Sep rates
- New + reactivation + expansion
- £2,813
- Oct, at Sep rates
October 2026 waterfall, opening to closing MRR
Adds Takes away MRR
Axis starts at £27,000 so the movements are visible. Movements are valued at the Sep month-end rate; the FX bar is the effect of the Oct rate on closing MRR (EUR 0.87 → 0.86, USD 0.79 → 0.77, GBP per unit, invented rates).
Six-month MRR roll-forward (£)
| Month | Opening | New | React. | Exp. | Contr. | Churn | FX | Closing |
|---|---|---|---|---|---|---|---|---|
| May | 21,675 | 995 | 0 | 576 | −240 | −948 | −6 | 22,052 |
| Jun | 22,052 | 942 | 0 | 419 | −127 | 0 | +5 | 23,290 |
| Jul | 23,290 | 1,575 | 300 | 795 | 0 | −1,734 | +40 | 24,265 |
| Aug | 24,265 | 1,015 | 1,088 | 1,081 | −535 | 0 | +9 | 26,923 |
| Sep | 26,923 | 1,710 | 0 | 288 | −90 | 0 | +22 | 28,853 |
| Oct | 28,853 | 765 | 350 | 1,698 | −243 | −2,743 | −198 | 28,482 |
Each row adds up: opening + new + reactivation + expansion − contraction − churn ± FX = closing. Rounded to whole pounds for display.
Outside MRR at 31 Oct
- TrialingExcluded until the first paid period£1,3133 subs
- PausedCounted as churn when paused£7722 subs
- Past due (in MRR)Still counted; churns if it becomes unpaid£8552 subs
- Cancel at period end (in MRR)Counted until the period ends£1,1252 subs
Stripe's support article says a subscription set to cancel at period end stops counting at the time of the request. Treated that way, closing MRR here would be £27,357.
Oct movements by customer
21 rows · worked-example customers first
| Customer | Movement | MRR Sep → Oct (native) | Movement £ | FX £ |
|---|---|---|---|---|
| cus_SB002B · Trial ended, first paid period (annual) | New | £0 → £400 | +400.00 | 0 |
| cus_SB008H · Returned after canceling in July | Reactivation | £0 → £350 | +350.00 | 0 |
| cus_SB009I · 50% repeating coupon ended (3 months) | Expansion | £250 → £500 | +250.00 | 0 |
| cus_SB001A · Added 2 seats (quantity 4 → 6) | Expansion | £360 → £540 | +180.00 | 0 |
| cus_SB004D · Downgraded annual plan ($9,000 → $6,000 a year) | Contraction | $750 → $500 | −197.50 | −10.00 |
| cus_SB005E · Canceled 14 Oct | Churn | £620 → £0 | −620.00 | 0 |
| cus_SB006F · Subscription paused (status paused) | Churn | £280 → £0 | −280.00 | 0 |
| cus_SB003C · No change; euro weakened | No movement | €960 → €960 | 0 | −9.60 |
| cus_SB007G · cancel_at_period_end set 20 Oct; ends 5 Nov | No movement | £900 → £900 | 0 | 0 |
| cus_SB069 | New | €0 → €346.67 | +301.60 | −3.46 |
| cus_SB070 | New | £0 → £63.75 | +63.75 | 0 |
| cus_SB066 | Expansion | €728 → €1,456 | +633.36 | −14.56 |
| cus_SB020 | Expansion | $920 → $1,265 | +272.55 | −25.30 |
| cus_SB042 | Expansion | £270 → £450 | +180.00 | 0 |
| cus_SB039 | Expansion | $870 → $986 | +91.64 | −19.72 |
| cus_SB045 | Expansion | £90 → £180 | +90.00 | 0 |
| cus_SB051 | Contraction | £630 → £585 | −45.00 | 0 |
| cus_SB067 | Churn | £630 → £0 | −630.00 | 0 |
| cus_SB047 | Churn | £585 → £0 | −585.00 | 0 |
| cus_SB048 | Churn | €514.80 → €0 | −447.88 | 0 |
| cus_SB017 | Churn | £180 → £0 | −180.00 | 0 |
Worked example (illustrative, fictional)
Sorrelby Software is a made-up UK SaaS business that bills in pounds, euros and dollars. Nine of its customers explain every line of a waterfall between 30 September and 31 October 2026. Rates are invented: €1 = £0.87 at 30 September and £0.86 at 31 October; $1 = £0.79 and £0.77.
| Key | What happened in Stripe | MRR 30 Sep | MRR 31 Oct (at Sep rate) | Movement | FX |
|---|---|---|---|---|---|
| A | £90 a seat monthly, quantity 4 → 6 |
£360.00 | £540.00 | Expansion +£180.00 | £0 |
| B | Annual £4,800; trialing on 30 Sep, paid in Oct |
£0 | £400.00 | New +£400.00 | £0 |
| C | €1,200 monthly, 20% forever coupon = €960 |
£835.20 | £835.20 | None | −£9.60 |
| D | Annual $9,000 → $6,000 ($750 → $500 a month) | £592.50 | £395.00 | Contraction −£197.50 | −£10.00 |
| E | £620 monthly, canceled 14 Oct |
£620.00 | £0 | Churn −£620.00 | £0 |
| F | £280 monthly, status became paused |
£280.00 | £0 | Churn −£280.00 | £0 |
| G | £900 monthly, cancel_at_period_end set 20 Oct, ends 5 Nov |
£900.00 | £900.00 | None (scheduled) | £0 |
| H | £350 monthly, canceled in July, back in Oct | £0 | £350.00 | Reactivation +£350.00 | £0 |
| I | £500 monthly; 50% repeating coupon ended |
£250.00 | £500.00 | Expansion +£250.00 | £0 |
The waterfall for these nine:
- Opening MRR: 360 + 835.20 + 592.50 + 620 + 280 + 900 + 250 = £3,837.70.
- New £400.00, reactivation £350.00, expansion 180 + 250 = £430.00.
- Contraction £197.50, churn 620 + 280 = £900.00.
- FX: C's €960 × (0.86 − 0.87) = −£9.60, D's $500 × (0.77 − 0.79) = −£10.00, so −£19.60.
- Closing: 3,837.70 + 400 + 350 + 430 − 197.50 − 900 − 19.60 = £3,900.60, which matches the sum of the nine closing values at October rates (540 + 400 + 825.60 + 385 + 900 + 350 + 500).
- ARR for these nine: 3,900.60 × 12 = £46,807.20.
Two judgement calls sit in that table. Customer I's coupon ending shows as expansion because discounts are subtracted from MRR; some teams prefer a separate "discount roll-off" line so the sales team doesn't get credit for it. Customer G is still in MRR here. Under the timing in Stripe's support article G would already be churn, making churn £1,800.00 and closing MRR £3,000.60 for these nine. Neither is wrong, but the pack must say which rule it uses.
Across all 62 paying customers in the report above, October opened at £28,852.80 and closed at £28,482.19 (ARR £341,786.28): £2,812.90 of new, reactivation and expansion against £2,985.38 of churn and contraction, with a weaker euro and dollar taking off £198.13.
Reconciling to the Stripe Dashboard
Your waterfall and Stripe's will differ; the job is to explain the gap line by line. The usual causes:
| Difference | Where to look |
|---|---|
| Scheduled cancellations | Subscriptions with cancel_at_period_end true and a future period end |
| Discount settings | Stripe's Configure options for recurring and one-time discounts versus your rule |
| Collection paused | Subscriptions with pause_collection set but status still active |
| Trials | Item-level trial offers exclude only the trialing items; legacy trial_end trials exclude the whole subscription |
| Currency | Your month-end rates versus Stripe's conversion |
| Cut-off | UTC dates in exports versus your account time zone |
Customer-level churn and expansion here also feed retention measures. For how to turn these movements into net and gross retention, see NRR calculation, and for the same movements tracked by signup month, see SaaS cohort retention. If sales reports ARR from the CRM, reconciling Stripe and Salesforce ARR covers the join.
Automating the waterfall with IVP.ai
The IVP.ai Data Layer reads subscriptions, items, prices, discounts and invoices from the Stripe API each night with read-only keys, stores the month-end snapshots, applies your written rules for discounts, pauses and scheduled cancellations, and converts at the rate table you approve. The waterfall then runs as a report with the reconciliation lines above, so the number on the board slide can be traced back to a customer and a subscription.
Deskless by IVP.ai can take the follow-up work. By default it flags and drafts rather than acting: listing the past_due customers who will become churn if they reach unpaid, or the scheduled cancellations worth a call before the period ends, and waiting for a person to decide.
One fintech saved over £120,000 compared with building the same data platform in-house (case study). More SaaS metrics templates are on the SaaS reporting hub.
To see the waterfall on your own Stripe account, start with the free 48-hour build. We connect up to three sources, clean the data and set one report or agent running on real data within 48 hours of read-only access. You then have 14 days of access to choose a plan or walk away.