Gross MRR Retention

GET https://api.chartmogul.com/v2/metrics/gross_mrr_retention

Retrieves the Gross MRR Retention rate for the specified time period.

curl -X GET "https://api.chartmogul.com/v2/metrics/gross_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": 94.5,
    "previous": 95.0,
    "percentage-change": -0.53
  }
}

This endpoint is not available to accounts that use the Shopify formula for churn rate.

Query parameters

start date required
The start date of the required period of data. An ISO-8601 formatted date, e.g. 2026-08-01. Must not be later than end.
end date required
The end date of the required period of data. An ISO-8601 formatted date, e.g. 2026-10-31.
interval string required
One of day, week, month, quarter, or year.
filters string 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 separate geo and plans parameters.
include_summary boolean optional default: false
Set to true to add the summary key to the response.
exclude_reactivations boolean optional default: false
Set to true to leave Reactivation MRR out of the calculation. Affects only the net rates in the response; the gross rates never include Reactivation MRR.
exclude_contractions boolean optional default: false
Set to true to leave Contraction MRR out of the calculation.
leaving_segment string 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:

gross_mrr_retention
The Gross MRR Retention rate for the interval, expressed as a percentage. For the current, incomplete interval, the rate is an estimate for the full interval.
net_mrr_retention, net_mrr_churn, gross_mrr_churn
The Net 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 Gross MRR Retention rate and the percentage change between the two (percentage-change).

Gross MRR Retention counts only contraction and churn, so it is always between 0% and 100%.