Net MRR Retention
GET https://api.chartmogul.com/v2/metrics/net_mrr_retention
Retrieves the Net MRR Retention rate for the specified time period.
curl -X GET "https://api.chartmogul.com/v2/metrics/net_mrr_retention" \
-u YOUR_API_KEY: \
-G \
-d start=2026-08-01 \
-d end=2026-09-30 \
-d interval=month \
-d include_summary=true
{
"entries": [
{
"date": "2026-08-31",
"starting_mrr": 1000000.0,
"expansion_mrr": 60000.0,
"expansion_customer_count": 12,
"contraction_mrr": -20000.0,
"contraction_customer_count": 4,
"churn_mrr": -30000.0,
"churn_customer_count": 6,
"reactivation_mrr": 5000.0,
"reactivation_customer_count": 1,
"net_mrr_retention": 101.5,
"gross_mrr_retention": 95.0,
"net_mrr_churn": -1.5,
"gross_mrr_churn": 5.0,
"entered_mrr": 0.0,
"entered_customer_count": 0,
"left_mrr": 0.0,
"left_customer_count": 0,
"expansion_left_mrr": 0.0,
"expansion_left_movements_mrr": 0.0,
"expansion_left_customer_count": 0,
"contraction_left_mrr": 0.0,
"contraction_left_movements_mrr": 0.0,
"contraction_left_customer_count": 0,
"currency_fluctuations_mrr": null,
"currency_fluctuations_customer_count": null,
"YoY_net_mrr_retention": 99.2,
"YoY_gross_mrr_retention": 94.1,
"YoY_net_mrr_churn": 0.8,
"YoY_gross_mrr_churn": 5.9,
"YoY_interval_start": "2025-09-01",
"YoY_interval_end": "2026-08-31"
},
{
"date": "2026-09-30",
"starting_mrr": 1015000.0,
"expansion_mrr": 20000.0,
"expansion_customer_count": 5,
"contraction_mrr": -15225.0,
"contraction_customer_count": 3,
"churn_mrr": -40600.0,
"churn_customer_count": 8,
"reactivation_mrr": 0.0,
"reactivation_customer_count": 0,
"net_mrr_retention": 96.47,
"gross_mrr_retention": 94.5,
"net_mrr_churn": 3.53,
"gross_mrr_churn": 5.5,
"entered_mrr": 0.0,
"entered_customer_count": 0,
"left_mrr": 0.0,
"left_customer_count": 0,
"expansion_left_mrr": 0.0,
"expansion_left_movements_mrr": 0.0,
"expansion_left_customer_count": 0,
"contraction_left_mrr": 0.0,
"contraction_left_movements_mrr": 0.0,
"contraction_left_customer_count": 0,
"currency_fluctuations_mrr": null,
"currency_fluctuations_customer_count": null,
"YoY_net_mrr_retention": 98.4,
"YoY_gross_mrr_retention": 93.7,
"YoY_net_mrr_churn": 1.6,
"YoY_gross_mrr_churn": 6.3,
"YoY_interval_start": "2025-10-01",
"YoY_interval_end": "2026-09-30"
}
],
"summary": {
"current": 96.47,
"previous": 101.5,
"percentage-change": -4.96
}
}
This endpoint is not available to accounts that use the Shopify formula for churn rate.
Query parameters
startdate required- The start date of the required period of data. An ISO-8601 formatted date, e.g.
2026-08-01. Must not be later thanend. enddate required- The end date of the required period of data. An ISO-8601 formatted date, e.g.
2026-10-31. intervalstring required- One of
day,week,month,quarter, oryear. filtersstring optional- A set of filters to limit the results, formatted as CFL. Copy URL-encoded CFL from the app (e.g.,
filters=currency~ANY~%27USD%27) or write the expression manually and enclose the key-value pair in double quotes (e.g.,"filters=currency~ANY~'USD'"). To limit the results to certain countries or plans, use a filter; there are no separategeoandplansparameters. include_summaryboolean optional default: false- Set to
trueto add thesummarykey to the response. exclude_reactivationsboolean optional default: false- Set to
trueto leave Reactivation MRR out of the calculation. Affects only the net rates in the response; the gross rates never include Reactivation MRR. exclude_contractionsboolean optional default: false- Set to
trueto leave Contraction MRR out of the calculation. leaving_segmentstring optional default: "proportional"- How to count MRR that moves out of the filtered segment, for example when a customer switches to a plan that the filter excludes. One of:
proportional(default) — counts only the part of that MRR that the customer lost as a contraction.total_churn— counts all of that MRR as churned.total_retention— counts all of that MRR as retained.
Response
In the response, the entries key contains an object for each interval, with the following data:
net_mrr_retention- The Net MRR Retention rate for the interval, expressed as a percentage. For the current, incomplete interval, the rate is an estimate for the full interval.
gross_mrr_retention,net_mrr_churn,gross_mrr_churn- The Gross MRR Retention, Net MRR Churn Rate and Gross MRR Churn Rate for the same interval, expressed as percentages.
starting_mrr- The MRR at the start of the interval, in cents.
expansion_mrr,contraction_mrr,churn_mrr,reactivation_mrr- The MRR movements during the interval, in cents. Contraction and churn are negative.
expansion_customer_count,contraction_customer_count,churn_customer_count,reactivation_customer_count- The number of customers with each MRR movement during the interval.
entered_mrr,entered_customer_count,left_mrr,left_customer_count- The MRR, in cents, and the number of customers that moved into or out of the filtered segment during the interval.
expansion_left_mrr,expansion_left_movements_mrr,expansion_left_customer_count,contraction_left_mrr,contraction_left_movements_mrr,contraction_left_customer_count- The MRR that moved out of the filtered segment, split by whether the customer's total MRR grew (expansion) or shrank (contraction).
currency_fluctuations_mrr,currency_fluctuations_customer_count- The MRR change caused by exchange rate fluctuations, in cents, and the number of customers it affected. Can be
null. YoY_net_mrr_retention,YoY_gross_mrr_retention,YoY_net_mrr_churn,YoY_gross_mrr_churn- The same rates for the twelve months that end on
date. YoY_interval_start,YoY_interval_end- The start and end dates of those twelve months.
The summary key is present when include_summary is true. It contains the values for the last complete month and the month before that (current and previous) of the Net MRR Retention rate and the percentage change between the two (percentage-change).
Net MRR Retention can be larger than 100%: a rate of 101.5% means that expansion and reactivation outweighed contraction and churn, and MRR from existing customers grew by 1.5% during that interval.