Cohorts

The /reports/cohort endpoint provides cohort-based analytics for your customers, including retention, churn, and MRR movements over time. This endpoint allows you to analyze customer behavior by time-based cohorts (e.g., by paid start date) or categorical cohorts (e.g., country or currency). It supports flexible filtering, currency conversion, and interval-based aggregation.

HTTP request

GET /reports/cohort

Query parameters

Parameter	Type	Required	Description
`date`	string	No	End date of the cohort period (YYYY-MM-DD). Defaults to current date.
`interval`	string	No	Aggregation interval: `day`, `week`, `month`, `quarter`, `year`. Defaults to `month`.
`baseCurrency`	string	No	Target currency for MRR conversion. Defaults to the user's base currency.
`breakdown`	string	No	Optional breakdown of cohorts: `country`, `currency`. Defaults to time-based cohort by `paid_started`.
`fix_fx`	boolean	No	If `true`, uses exchange rates fixed to cohort start date instead of period-specific rates. Defaults to `false`.
`region`	string	No	Filter by region name(s) or country code(s). Multiple values separated by spaces.
`currency`	string	No	Filter by customer currency. Multiple values separated by spaces.
`industry`	string	No	Filter by industry. Multiple values separated by spaces.
`channel`	string	No	Filter by sales or marketing channel. Multiple values separated by spaces.
`size`	string	No	Filter by company size. Multiple values separated by spaces.

Response

Success (time-based cohort)

Status: 200 OK

Body example:

{
  "result": {
    "list": [
      {
        "cohort_group": "2024-01-31",
        "initial_mrr": 12000,
        "initial_customers": 15,
        "periods": [
          {
            "mrr_retained": 12000,
            "customers_retained": 15,
            "mrr_retention": 100,
            "customer_retention": 100,
            "mrr_retention_relative": 100,
            "customer_retention_relative": 100,
            "mrr_churn": 0,
            "customer_churn": 0,
            "mrr_churn_relative": 0,
            "customer_churn_relative": 0
          },
          {
            "mrr_retained": 11000,
            "customers_retained": 14,
            "mrr_retention": 91.67,
            "customer_retention": 93.33,
            "mrr_retention_relative": 91.67,
            "customer_retention_relative": 93.33,
            "mrr_churn": 8.33,
            "customer_churn": 6.67,
            "mrr_churn_relative": 8.33,
            "customer_churn_relative": 6.67
          }
        ]
      },
      {
        "cohort_group": "average",
        "periods": [
          {
            "mrr_retained": 23000,
            "customers_retained": 29,
            "mrr_retention": 96.67,
            "customer_retention": 96.67,
            "mrr_retention_relative": 100,
            "customer_retention_relative": 100,
            "mrr_churn": 3.33,
            "customer_churn": 3.33,
            "mrr_churn_relative": 0,
            "customer_churn_relative": 0
          }
        ]
      }
    ]
  }
}

Success (country breakdown)

Query: ?format=chart&breakdown=country

Body example:

{
  "breakdown": "country",
  "result": [
    {
      "period": 0,
      "breakdown": {
        "US": {
          "label": "US",
          "mrr_retained": 5000,
          "customers_retained": 8,
          "mrr_retention": 100,
          "customer_retention": 100
        },
        "DE": {
          "label": "DE",
          "mrr_retained": 3000,
          "customers_retained": 5,
          "mrr_retention": 100,
          "customer_retention": 100
        }
      }
    }
  ]
}

Response fields

Field	Type	Description
`cohort_group`	string	The cohort identifier. Date for time-based cohorts or category value for breakdowns (e.g., country, currency).
`initial_mrr`	number	MRR at the start of the cohort (in base currency).
`initial_customers`	number	Number of customers at the start of the cohort.
`periods`	array	Array of periods relative to cohort start, containing retention metrics and MRR/customer changes.
`mrr_retained`	number	Total MRR retained for this period (base currency).
`customers_retained`	number	Total customers retained for this period.
`mrr_retention`	number	Percentage of MRR retained relative to the cohort's initial MRR.
`customer_retention`	number	Percentage of customers retained relative to initial cohort size.
`mrr_retention_relative`	number	MRR retention relative to the previous period.
`customer_retention_relative`	number	Customer retention relative to the previous period.
`mrr_churn`	number	Churned MRR percentage (100 - `mrr_retention`).
`customer_churn`	number	Churned customer percentage (100 - `customer_retention`).
`mrr_churn_relative`	number	Churned MRR percentage relative to previous period.
`customer_churn_relative`	number	Churned customer percentage relative to previous period.

Usage notes

Currency conversion: The baseCurrency parameter converts all MRR amounts to a single currency. Exchange rates are either period-specific or fixed to cohort start (fix_fx=true).
Interval handling:
- Day, week, month, quarter, year.
- Daily cohorts are automatically aggregated weekly to avoid excessive granularity.
Breakdowns:
- By default, cohorts are time-based (by paid_started).
- Optional categorical breakdowns: country or currency.
Empty cohorts: Cohorts with no data return 0 values and are included to maintain continuity in the timeline.
Chart-ready format: When format=chart is used, the response is structured with period indexes and breakdown objects for easier visualization in dashboards.

This endpoint is ideal for tracking cohort retention trends, MRR growth, and customer churn over time, helping teams understand product adoption and revenue retention at a granular level.