MRR timeline

Get a detailed timeline of Monthly Recurring Revenue (MRR) and customer movements for your account. You can optionally break down the data by plan, currency, billing frequency, pricing model, customer subtype, region/market, country, industry, customer age, or size. The report also calculates churn, retention, ARPA, ASP, LTV, quick ratio, and FX adjustments.

GET /reports/mrr

Query parameters

Parameter	Type	Description
date	string	Optional date range for the report (e.g., `20250901-20251001`). Defaults to last 365 days.
interval	string	`day`, `week`, `quarter`, or `month`. Defaults to `month`.
breakdown	string	Group MRR by `plan`, `currency`, `billing_freq`, `pricing_model`, `payment_method`, `subtype`, `market`, `country`, `industry`, `age`, `size`.
baseCurrency	string	Optional base currency for FX conversion. Defaults to the account's base currency.
customer	string	Filter by a specific customer ID.
plan	string	Filter by plan IDs (space-separated for multiple).
currency	string	Filter by currency codes (space-separated).
billing_freq	string	Filter by billing frequency (month/year).
pricing_model	string	Filter by pricing model (`licensed`, `metered`).
payment_method	string	Filter by payment method (e.g., `visa`, `paypal`, `ach`).
subtype	string	Filter by customer subtype.
region	string	Filter by region (maps to countries).
country	string	Filter by specific country codes.
industry	string	Filter by customer industry.
age	string	Filter by customer age in months or ranges (e.g., `0-6 6-12`).
size	string	Filter by customer size.
status	string	Filter by subscription status.
category	string	Filter by MRR movement category (`new`, `expansion`, `contraction`, `churn`, `reactivation`).
fix_fx	boolean	If `true`, uses a fixed FX rate from the first period instead of period-specific rates.

Example response

200 OK
{
  "currency": "usd",
  "breakdown": "plan",
  "result": [
    {
      "date": "2025-09-01",
      "end_date": "2025-09-30",
      "new": 5000,
      "expansion": 1000,
      "contraction": -500,
      "churn": -200,
      "reactivation": 100,
      "mrr_diff": 5400,
      "customers_diff": 5,
      "total_mrr": 10500,
      "total_arr": 126000,
      "total_customers": 50,
      "arpa": 210,
      "asp": 1000,
      "quick_ratio": 2.5,
      "customer_churn_rate": 0.04,
      "mrr_churn_rate": 0.02,
      "net_mrr_churn_rate": 0.01,
      "customer_retention_rate": 96,
      "mrr_retention_rate": 98,
      "nrr": 99,
      "customer_churn_avg": 0.035,
      "ltv": 5250,
      "fx_adjustment": 50,
      "breakdown": {
        "basic": {
          "label": "Basic Plan",
          "new": 2000,
          "expansion": 500,
          "contraction": -100,
          "churn": -50,
          "reactivation": 0,
          "mrr_diff": 2350,
          "customers_diff": 2,
          "total_mrr": 5000,
          "total_arr": 60000,
          "total_customers": 25,
          "arpa": 200,
          "asp": 1000,
          "customer_churn_rate": 0.02,
          "customer_churn_avg": 0.018,
          "ltv": 10000,
          "fx_adjustment": 20
        },
        "pro": {
          "label": "Pro Plan",
          "...": "..."
        }
      }
    }
  ]
}

Result properties

Property	Type	Description
date	string	Start of the period (yyyy-MM-dd).
end_date	string	End of the period.
new	integer	MRR from new customers.
expansion	integer	MRR from existing customers upgrading.
contraction	integer	MRR lost from downgrades.
churn	integer	MRR lost from churned customers.
reactivation	integer	MRR from reactivated customers.
mrr_diff	integer	Total MRR movement for the period.
customers_diff	integer	Total customer movement for the period.
total_mrr	integer	Total MRR in base currency at period end.
total_arr	integer	Annualized recurring revenue (MRR × 12).
total_customers	integer	Total customers at period end.
arpa	integer	Average revenue per account.
asp	integer	Average subscription price for new customers.
quick_ratio	float	Ratio of growth (new + expansion) to losses (contraction + churn).
customer_churn_rate	float	Churn rate for customers during period.
mrr_churn_rate	float	Churn rate for MRR during period.
net_mrr_churn_rate	float	Net MRR churn (churn + contraction + expansion + reactivation).
customer_retention_rate	float	100% - customer churn rate.
mrr_retention_rate	float	100% - MRR churn rate.
nrr	float	Net revenue retention.
customer_churn_avg	float	Average customer churn over past 180 days (or 25 weeks).
ltv	integer	Lifetime value estimate based on ARPA / average monthly churn.
fx_adjustment	integer	FX rate adjustment applied to MRR.

Breakdown properties

If breakdown is used, the breakdown object contains keys corresponding to breakdown values (plan IDs, currency codes, countries, etc.) with the following structure:

Property	Type	Description
label	string	Display label for the breakdown value.
total_mrr	integer	Total MRR for this breakdown.
total_arr	integer	Total ARR for this breakdown.
total_customers	integer	Total customers in this breakdown.
new	integer	MRR from new customers.
expansion	integer	MRR from upgrades.
contraction	integer	MRR lost from downgrades.
churn	integer	MRR lost from churn.
reactivation	integer	MRR from reactivations.
mrr_diff	integer	Net MRR movement.
customers_diff	integer	Net customer movement.
new_customers	integer	Number of new customers.
expansion_customers	integer	Number of customers expanding.
contraction_customers	integer	Number of customers contracting.
churn_customers	integer	Number of churned customers.
reactivation_customers	integer	Number of reactivated customers.
arpa	integer	Average revenue per account.
asp	integer	Average subscription price.
customer_churn_rate	float	Customer churn rate for this breakdown.
customer_churn_avg	float	Average churn over prior periods.
ltv	integer	Lifetime value estimate.
fx_adjustment	integer	FX adjustment for this breakdown.