Integrations

MRR and ARR waterfall from Stripe

An MRR waterfall explains how monthly recurring revenue got from the opening figure to the closing one: new, reactivation, expansion, contraction, churn and currency. This guide builds it from Stripe subscriptions, items, prices and coupons, with the rules that make it add up and reconcile to the Stripe Dashboard.

By Simon DuttonLast reviewed

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

  1. Recurring licensed items only. Skip prices where type is one_time and items where recurring.usage_type is metered; usage revenue gets its own line, not MRR.
  2. Monthly value per item = unit_amount × quantity ÷ months in the interval. A yearly price is ÷ 12; a monthly price with interval_count of 3 is ÷ 3. Tiered prices have no single unit_amount, so price those from the tier table or from the last invoice line.
  3. Taxes out. If a price's tax_behavior is inclusive, its amount contains tax, so strip it before it enters MRR.
  4. Discounts. Decide once and write it down. The method here subtracts forever and repeating coupons while they are active and ignores once coupons, roughly matching Stripe's "subtract recurring discounts" setting. An amount_off coupon comes off each invoice, so on an annual price divide it by 12 too.
  5. Status. active and past_due count. trialing, paused, canceled, unpaid, incomplete and incomplete_expired contribute zero. Treat a set pause_collection as zero as well: Stripe's reference says it leaves status unchanged, so a status filter alone will not catch it.
  6. 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.
  7. 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.

IVP.ai / Data Layer

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

MRR waterfall for October 2026, fictional dataOpening MRR £28,852.80. New plus £765.35; React. plus £350.00; Expansion plus £1,697.55; Contraction minus £242.50; Churn minus £2,742.88; FX minus £198.13. Closing MRR £28,482.19. The vertical axis starts at £27,000, not zero.£27k£28k£29k£30k£31k£32k£33k£28.9kOpening+£765New+£350React.+£1,698Expansion−£243Contraction−£2,743Churn−£198FX£28.5kClosing

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 (£)

Monthly MRR roll-forward: opening, new, reactivation, expansion, contraction, churn, FX and closing MRR in pounds
MonthOpeningNewReact.Exp.Contr.ChurnFXClosing
May21,6759950576−240−948−622,052
Jun22,0529420419−1270+523,290
Jul23,2901,5753007950−1,734+4024,265
Aug24,2651,0151,0881,081−5350+926,923
Sep26,9231,7100288−900+2228,853
Oct28,8537653501,698−243−2,743−19828,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-level MRR movements in October 2026, with native currency MRR, movement and FX effect in pounds
CustomerMovementMRR Sep → Oct (native)Movement £FX £
cus_SB002B · Trial ended, first paid period (annual)New£0 → £400+400.000
cus_SB008H · Returned after canceling in JulyReactivation£0 → £350+350.000
cus_SB009I · 50% repeating coupon ended (3 months)Expansion£250 → £500+250.000
cus_SB001A · Added 2 seats (quantity 4 → 6)Expansion£360 → £540+180.000
cus_SB004D · Downgraded annual plan ($9,000 → $6,000 a year)Contraction$750 → $500−197.50−10.00
cus_SB005E · Canceled 14 OctChurn£620 → £0−620.000
cus_SB006F · Subscription paused (status paused)Churn£280 → £0−280.000
cus_SB003C · No change; euro weakenedNo movement€960 → €9600−9.60
cus_SB007G · cancel_at_period_end set 20 Oct; ends 5 NovNo movement£900 → £90000
cus_SB069New€0 → €346.67+301.60−3.46
cus_SB070New£0 → £63.75+63.750
cus_SB066Expansion€728 → €1,456+633.36−14.56
cus_SB020Expansion$920 → $1,265+272.55−25.30
cus_SB042Expansion£270 → £450+180.000
cus_SB039Expansion$870 → $986+91.64−19.72
cus_SB045Expansion£90 → £180+90.000
cus_SB051Contraction£630 → £585−45.000
cus_SB067Churn£630 → £0−630.000
cus_SB047Churn£585 → £0−585.000
cus_SB048Churn€514.80 → €0−447.880
cus_SB017Churn£180 → £0−180.000

62 paying customers at 31 Oct · ARR = MRR × 12 · taxes and metered items excluded

Illustrative data

Illustrative, fictional data. The company, customer IDs, subscriptions and exchange rates are invented; not customer results or a live product screenshot.

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.

Questions

Frequently asked questions

How does Stripe calculate MRR?

Stripe's Billing analytics documentation defines MRR as the sum of the monthly-normalised value of all active and past_due subscriptions. It excludes taxes, free-plan subscribers and metered usage products. Canceled and unpaid subscriptions count as churn. Whether recurring and one-time discounts reduce MRR is a setting you can configure, although permanent recurring discounts are always subtracted.

How are annual plans counted in Stripe MRR?

Annual prices are divided by 12, so a 600 USD yearly plan contributes 50 USD a month, which is the example Stripe's own documentation uses. If you build the figure yourself, divide by the months in the price's recurring interval multiplied by its interval_count, so a monthly price billed every three months is divided by three. Do the same with fixed-amount coupons.

Why doesn't my own MRR figure match the Stripe Dashboard?

The usual reasons are rule differences, not errors. Stripe stops counting a subscription set to cancel at period end from the time of the request, its discount settings may differ from yours, subscriptions with collection paused keep an active status, and exports use UTC while charts use your account time zone. List each difference as a reconciling line rather than forcing the totals to agree.

How do I get ARR from Stripe?

For a subscription business, ARR is normally MRR multiplied by 12 at a point in time. It is a run-rate, not recognised revenue or cash. Take closing MRR from your waterfall in your reporting currency, multiply by 12, and state which rules for discounts, trials, pauses and scheduled cancellations sit behind it, because those rules move the ARR figure too.

Do free trials count towards MRR in Stripe?

No. According to Stripe's documentation, a subscription in a legacy free trial set with trial_end is excluded from MRR in full until the trial ends. With item-level trial offers, only the items currently on trial are excluded and the other items on the same subscription still count. When the trial converts, the subscription shows as new MRR.

About the author

Simon Dutton

Simon has more than 10 years of experience as a data scientist, working with start-ups, SMEs, Google and the CMA.

Last reviewed 13 November 2026.

Your first report or agent in 48 hours.

Tell us which systems feed it. We connect them, clean the data and set the report running automatically. If it isn’t useful, walk away.