MRR¶
Monthly Recurring Revenue computed by the Tidemill engine.
How MRR is normalised¶
MRR converts every billing interval to a monthly rate:
| Interval | Formula |
|---|---|
| month | amount / interval_count |
| year | amount / (12 * interval_count) |
| week | amount * 52 / (12 * interval_count) |
| day | amount * 365 / (12 * interval_count) |
Only active subscriptions contribute to current MRR. All arithmetic uses integer cents to avoid floating-point drift.
In [17]:
Copied!
from tidemill import reports
from tidemill.reports.client import TidemillClient
reports.setup()
START, END = "2025-06-01", "2026-03-31"
tm = TidemillClient()
from tidemill import reports
from tidemill.reports.client import TidemillClient
reports.setup()
START, END = "2025-06-01", "2026-03-31"
tm = TidemillClient()
1. MRR Snapshot¶
Current Monthly Recurring Revenue and annualised ARR.
In [18]:
Copied!
reports.mrr.style_snapshot(reports.mrr.snapshot(tm))
reports.mrr.style_snapshot(reports.mrr.snapshot(tm))
Out[18]:
| MRR | ARR |
|---|---|
| $1,068.33 | $12,819.96 |
2. MRR Breakdown (movements)¶
Tidemill classifies every MRR change into a movement type:
| Movement | Meaning |
|---|---|
| new | First subscription for a customer |
| expansion | Upgrade or additional subscription |
| contraction | Downgrade (lower plan/fewer seats) |
| churn | Cancellation — customer lost entirely |
| reactivation | Previously churned customer returns |
The breakdown endpoint sums these over the full period.
In [19]:
Copied!
reports.mrr.plot_breakdown(reports.mrr.breakdown(tm, START, END))
reports.mrr.plot_breakdown(reports.mrr.breakdown(tm, START, END))
3. Quick Ratio¶
Growth efficiency ratio:
$$\text{Quick Ratio} = \frac{\text{new} + \text{expansion} + \text{reactivation}}{|\text{churn}| + |\text{contraction}|}$$
Interprets how much MRR is added for each dollar lost.
| Ratio | Interpretation |
|---|---|
| > 4 | Excellent — strong, efficient growth |
| 2 – 4 | Healthy growth |
| 1 – 2 | Slow growth |
| < 1 | Contracting — losses exceed gains |
In [20]:
Copied!
reports.mrr.style_quick_ratio(reports.mrr.quick_ratio(tm, START, END))
reports.mrr.style_quick_ratio(reports.mrr.quick_ratio(tm, START, END))
Out[20]:
| New | Expansion | Reactivation | Gains | Churn | Contraction | Losses | Quick Ratio |
|---|---|---|---|---|---|---|---|
| $1,487.33 | $118.00 | $99.00 | $1,704.33 | $558.00 | $118.00 | $676.00 | 2.52 |
4. Monthly MRR with movement split¶
Query MRR breakdown per month to show how new, expansion, contraction, and churn compose each month's MRR change.
In [21]:
Copied!
wf = reports.mrr.waterfall(tm, START, END)
reports.mrr.style_waterfall(wf)
wf = reports.mrr.waterfall(tm, START, END)
reports.mrr.style_waterfall(wf)
Out[21]:
| starting_mrr | new | expansion | reactivation | contraction | churn | net_change | ending_mrr | |
|---|---|---|---|---|---|---|---|---|
| period | ||||||||
| Jun 2025 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 |
| Jul 2025 | $0.00 | $1,007.33 | $0.00 | $0.00 | $0.00 | $-40.00 | $967.33 | $967.33 |
| Aug 2025 | $967.33 | $80.00 | $59.00 | $0.00 | $0.00 | $-80.00 | $59.00 | $1,026.33 |
| Sep 2025 | $1,026.33 | $0.00 | $0.00 | $0.00 | $-59.00 | $-119.00 | $-178.00 | $848.33 |
| Oct 2025 | $848.33 | $160.00 | $0.00 | $20.00 | $0.00 | $-40.00 | $140.00 | $988.33 |
| Nov 2025 | $988.33 | $0.00 | $59.00 | $79.00 | $-59.00 | $-119.00 | $-40.00 | $948.33 |
| Dec 2025 | $948.33 | $140.00 | $0.00 | $0.00 | $0.00 | $-20.00 | $120.00 | $1,068.33 |
| Jan 2026 | $1,068.33 | $100.00 | $0.00 | $0.00 | $0.00 | $-100.00 | $0.00 | $1,068.33 |
| Feb 2026 | $1,068.33 | $0.00 | $0.00 | $0.00 | $0.00 | $-40.00 | $-40.00 | $1,028.33 |
| Mar 2026 | $1,028.33 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 | $0.00 | $1,028.33 |
4a. Per-customer movement log¶
Drill into the individual movements that compose each month's waterfall. Every row is a single customer's MRR change — new, expansion, reactivation, contraction, or churn — with monthly subtotals that should match the waterfall table above.
In [22]:
Copied!
ml = reports.mrr.movement_log(tm, START, END)
reports.mrr.style_movement_log(ml)
ml = reports.mrr.movement_log(tm, START, END)
reports.mrr.style_movement_log(ml)
Out[22]:
| month | date | customer | customer_id | movement | amount |
|---|---|---|---|---|---|
| 2025-07 | 2025-07-01 | Active Annual Enterprise #7 | cus_ULeP4MdsGIqA3N | new | $207.50 |
| 2025-07 | 2025-07-01 | Active Annual Pro #6 | cus_ULeP2nHUy4PfEW | new | $65.83 |
| 2025-07 | 2025-07-01 | Active Monthly Pro #4 | cus_ULePdAg7TfFaRx | new | $79.00 |
| 2025-07 | 2025-07-01 | Active Monthly Pro #5 | cus_ULePZEpGaYDqub | new | $79.00 |
| 2025-07 | 2025-07-01 | Active Starter #1 | cus_ULeOmo28L85BDt | new | $20.00 |
| 2025-07 | 2025-07-01 | Active Starter #2 | cus_ULePYzNMidnEnZ | new | $20.00 |
| 2025-07 | 2025-07-01 | Active Starter Heavy #3 | cus_ULePUoQI3jKcEM | new | $20.00 |
| 2025-07 | 2025-07-01 | Churned Pro #11 | cus_ULeP0p3hQP4tXH | new | $79.00 |
| 2025-07 | 2025-07-01 | Churned Starter #8 | cus_ULePpEt37T6vDX | new | $20.00 |
| 2025-07 | 2025-07-01 | Churn→Reactivate Pro #16 | cus_ULeQx6mikUSGsG | new | $79.00 |
| 2025-07 | 2025-07-01 | Churn→Reactivate Starter #15 | cus_ULeQX6MBPeb0ao | new | $20.00 |
| 2025-07 | 2025-07-01 | Downgraded Pro→Starter #10 | cus_ULePlU5uLDHBFQ | new | $79.00 |
| 2025-07 | 2025-07-01 | Late Churned Starter #13 | cus_ULePffUmdz4BT2 | new | $20.00 |
| 2025-07 | 2025-07-01 | Late Downgraded Pro→Starter #14 | cus_ULeQhHVGpDylFL | new | $79.00 |
| 2025-07 | 2025-07-01 | Upgraded Starter→Pro #12 | cus_ULePFJs2l5ftYr | new | $20.00 |
| 2025-07 | 2025-07-01 | Upgraded Starter→Pro #9 | cus_ULePzVuCb6JBeL | new | $20.00 |
| 2025-07 | 2025-07-01 | Failed Payment Starter #17 | cus_ULeQpBsSlOcLTi | churn | $-20.00 |
| 2025-07 | 2025-07-01 | Trial→Expired #19 | cus_ULeQ0tP6GqIqKi | churn | $-20.00 |
| 2025-07 | 2025-07-31 | Trial Jul →churn #21 | cus_ULeQAuSXtSlc5a | new | $20.00 |
| 2025-07 | 2025-07-31 | Trial Jul →churn #22 | cus_ULeQSDYvBlAQLW | new | $20.00 |
| 2025-07 | 2025-07-31 | Trial Jul →churn #23 | cus_ULeQPnobEOJTdB | new | $20.00 |
| 2025-07 | 2025-07-31 | Trial Jul →convert #20 | cus_ULeQWLfzuwfTyC | new | $20.00 |
| 2025-07 | 2025-07-31 | Trial→Active Starter #18 | cus_ULeQWt3mB3sUz4 | new | $20.00 |
| 2025-07 | new: $1,007.33 | churn: $-40.00 | $967.33 | |||
| 2025-08 | 2025-08-01 | Upgraded Starter→Pro #9 | cus_ULePzVuCb6JBeL | expansion | $59.00 |
| 2025-08 | 2025-08-01 | Churn→Reactivate Starter #15 | cus_ULeQX6MBPeb0ao | churn | $-20.00 |
| 2025-08 | 2025-08-01 | Trial Jul →churn #21 | cus_ULeQAuSXtSlc5a | churn | $-20.00 |
| 2025-08 | 2025-08-01 | Trial Jul →churn #22 | cus_ULeQSDYvBlAQLW | churn | $-20.00 |
| 2025-08 | 2025-08-01 | Trial Jul →churn #23 | cus_ULeQPnobEOJTdB | churn | $-20.00 |
| 2025-08 | 2025-08-31 | Trial Aug →churn #27 | cus_ULeSGIcAjuvgrT | new | $20.00 |
| 2025-08 | 2025-08-31 | Trial Aug →convert #24 | cus_ULeRrPC40IFaif | new | $20.00 |
| 2025-08 | 2025-08-31 | Trial Aug →convert #25 | cus_ULeSo3PeqwKWzM | new | $20.00 |
| 2025-08 | 2025-08-31 | Trial Aug →convert #26 | cus_ULeS0TRSWVhFuj | new | $20.00 |
| 2025-08 | new: $80.00 | expansion: $59.00 | churn: $-80.00 | $59.00 | |||
| 2025-09 | 2025-09-01 | Downgraded Pro→Starter #10 | cus_ULePlU5uLDHBFQ | contraction | $-59.00 |
| 2025-09 | 2025-09-01 | Churned Starter #8 | cus_ULePpEt37T6vDX | churn | $-20.00 |
| 2025-09 | 2025-09-01 | Churn→Reactivate Pro #16 | cus_ULeQx6mikUSGsG | churn | $-79.00 |
| 2025-09 | 2025-09-01 | Trial Aug →churn #27 | cus_ULeSGIcAjuvgrT | churn | $-20.00 |
| 2025-09 | contraction: $-59.00 | churn: $-119.00 | $-178.00 | |||
| 2025-10 | 2025-10-01 | Trial Sep →churn #30 | cus_ULeTXiQGK6dkja | new | $20.00 |
| 2025-10 | 2025-10-01 | Trial Sep →churn #31 | cus_ULeT9OYMHGsFS6 | new | $20.00 |
| 2025-10 | 2025-10-01 | Trial Sep →convert #28 | cus_ULeTzx7snOUDxd | new | $20.00 |
| 2025-10 | 2025-10-01 | Trial Sep →convert #29 | cus_ULeTVlnGI3M9eb | new | $20.00 |
| 2025-10 | 2025-10-01 | Churn→Reactivate Starter #15 | cus_ULeQX6MBPeb0ao | reactivation | $20.00 |
| 2025-10 | 2025-10-01 | Trial Sep →churn #30 | cus_ULeTXiQGK6dkja | churn | $-20.00 |
| 2025-10 | 2025-10-01 | Trial Sep →churn #31 | cus_ULeT9OYMHGsFS6 | churn | $-20.00 |
| 2025-10 | 2025-10-31 | Trial Oct →churn #34 | cus_ULeVNwHMuukNRg | new | $20.00 |
| 2025-10 | 2025-10-31 | Trial Oct →churn #35 | cus_ULeVAcwU6VJHz0 | new | $20.00 |
| 2025-10 | 2025-10-31 | Trial Oct →convert #32 | cus_ULeVXcQjzR9s20 | new | $20.00 |
| 2025-10 | 2025-10-31 | Trial Oct →convert #33 | cus_ULeV4oJlMp1f7y | new | $20.00 |
| 2025-10 | new: $160.00 | reactivation: $20.00 | churn: $-40.00 | $140.00 | |||
| 2025-11 | 2025-11-01 | Upgraded Starter→Pro #12 | cus_ULePFJs2l5ftYr | expansion | $59.00 |
| 2025-11 | 2025-11-01 | Churn→Reactivate Pro #16 | cus_ULeQx6mikUSGsG | reactivation | $79.00 |
| 2025-11 | 2025-11-01 | Late Downgraded Pro→Starter #14 | cus_ULeQhHVGpDylFL | contraction | $-59.00 |
| 2025-11 | 2025-11-01 | Churned Pro #11 | cus_ULeP0p3hQP4tXH | churn | $-79.00 |
| 2025-11 | 2025-11-01 | Trial Oct →churn #34 | cus_ULeVNwHMuukNRg | churn | $-20.00 |
| 2025-11 | 2025-11-01 | Trial Oct →churn #35 | cus_ULeVAcwU6VJHz0 | churn | $-20.00 |
| 2025-11 | expansion: $59.00 | reactivation: $79.00 | contraction: $-59.00 | churn: $-119.00 | $-40.00 | |||
| 2025-12 | 2025-12-01 | Trial Nov →churn #37 | cus_ULeX2NUV9VMrag | new | $20.00 |
| 2025-12 | 2025-12-01 | Trial Nov →convert #36 | cus_ULeXlXhpnMNmGP | new | $20.00 |
| 2025-12 | 2025-12-01 | Trial Nov →churn #37 | cus_ULeX2NUV9VMrag | churn | $-20.00 |
| 2025-12 | 2025-12-31 | Trial Dec →churn #39 | cus_ULeYaFisWOH44u | new | $20.00 |
| 2025-12 | 2025-12-31 | Trial Dec →churn #40 | cus_ULeYERehvTbZpT | new | $20.00 |
| 2025-12 | 2025-12-31 | Trial Dec →churn #41 | cus_ULeY5eHSrMRuC1 | new | $20.00 |
| 2025-12 | 2025-12-31 | Trial Dec →churn #42 | cus_ULeYRipajFF1k1 | new | $20.00 |
| 2025-12 | 2025-12-31 | Trial Dec →convert #38 | cus_ULeYMtHrr3bmDQ | new | $20.00 |
| 2025-12 | new: $140.00 | churn: $-20.00 | $120.00 | |||
| 2026-01 | 2026-01-01 | Late Churned Starter #13 | cus_ULePffUmdz4BT2 | churn | $-20.00 |
| 2026-01 | 2026-01-01 | Trial Dec →churn #39 | cus_ULeYaFisWOH44u | churn | $-20.00 |
| 2026-01 | 2026-01-01 | Trial Dec →churn #40 | cus_ULeYERehvTbZpT | churn | $-20.00 |
| 2026-01 | 2026-01-01 | Trial Dec →churn #41 | cus_ULeY5eHSrMRuC1 | churn | $-20.00 |
| 2026-01 | 2026-01-01 | Trial Dec →churn #42 | cus_ULeYRipajFF1k1 | churn | $-20.00 |
| 2026-01 | 2026-01-31 | Trial Jan →churn #46 | cus_ULebNz4H3foUb5 | new | $20.00 |
| 2026-01 | 2026-01-31 | Trial Jan →churn #47 | cus_ULebXkJkdARhzd | new | $20.00 |
| 2026-01 | 2026-01-31 | Trial Jan →convert #43 | cus_ULeaHwmJ3Wp9TY | new | $20.00 |
| 2026-01 | 2026-01-31 | Trial Jan →convert #44 | cus_ULeaJueIWOEtlW | new | $20.00 |
| 2026-01 | 2026-01-31 | Trial Jan →convert #45 | cus_ULebmy9UYHvobS | new | $20.00 |
| 2026-01 | new: $100.00 | churn: $-100.00 | $0.00 | |||
| 2026-02 | 2026-02-01 | Trial Jan →churn #46 | cus_ULebNz4H3foUb5 | churn | $-20.00 |
| 2026-02 | 2026-02-01 | Trial Jan →churn #47 | cus_ULebXkJkdARhzd | churn | $-20.00 |
| 2026-02 | churn: $-40.00 | $-40.00 |
In [23]:
Copied!
reports.mrr.plot_waterfall(wf)
reports.mrr.plot_waterfall(wf)
In [24]:
Copied!
reports.mrr.plot_trend(reports.mrr.trend(tm, START, END))
reports.mrr.plot_trend(reports.mrr.trend(tm, START, END))
In [ ]:
Copied!