Analytics

The subscription analytics endpoints power the Admin analytics dashboard. You can fetch KPI summary cards, retrieve grouped time-series data for charts, export a flattened dataset as JSON or CSV, and trigger a manual rebuild of daily analytics snapshots for a historical range. All routes require an authenticated Medusa Admin user. Read routes share a common filter contract; the rebuild route uses a separate request body.

All routes require an authenticated Medusa Admin user. Unauthenticated requests return 401.

Metric keys

Key	Unit	Description
`mrr`	`currency`	Monthly recurring revenue
`churn_rate`	`percentage`	Subscriber churn rate
`ltv`	`currency`	Estimated lifetime value
`active_subscriptions_count`	`count`	Number of active subscriptions
`created_subscriptions_count`	`count`	Number of subscriptions created on a UTC day

MRR and LTV resolve to null when the selected dataset lacks a single valid currency context.

created_subscriptions_count is returned by the trends response only. KPI cards remain mrr, churn_rate, ltv, and active_subscriptions_count.

Shared filter parameters

All three read routes (/kpis, /trends, /export) accept the same filter parameters.

string

ISO datetime lower bound. Must be on or before date_to. Maximum analytics window is 731 days.

string

ISO datetime upper bound.

string | string[]

Filter by subscription status. Supported values: active, paused, cancelled, past_due.

string | string[]

Filter by product ID. Accepts a single value or an array.

string | string[]

Filter by cadence using serialized tokens such as week:1, month:1, or year:1. Accepts a single value or an array.

string

Time bucket granularity. One of day, week, or month. Defaults to day.

string

Timezone for bucket boundaries. Only UTC is supported in MVP.

GET /admin/subscription-analytics/kpis

Returns the KPI summary payload used by the Admin analytics overview cards.

Response

object[]

required

Array of KPI summaries, one per supported metric key.

Show KPI properties

string

Metric key.

string

Human-readable label.

number | null

Computed metric value, or null when not computable for the selected range.

string

One of currency, percentage, or count.

string | null

Currency code for currency metrics, or null.

number

Decimal precision for display formatting.

number | null

Value for the prior comparable period.

number | null

Absolute change from previous period.

number | null

Percentage change from previous period.

object

required

Resolved filter values used for the query.

string

required

Analytics schema version identifier.

string

required

Timestamp when the response was generated.

Response example

{
  "filters": {
    "date_from": "2026-04-01T00:00:00.000Z",
    "date_to": "2026-04-30T23:59:59.999Z",
    "status": ["active", "past_due"],
    "product_id": ["prod_123"],
    "frequency": [
      {
        "interval": "month",
        "value": 1
      }
    ],
    "group_by": "day"
  },
  "metrics_version": "analytics-v1",
  "generated_at": "2026-05-01T10:00:00.000Z",
  "kpis": [
    {
      "key": "mrr",
      "label": "MRR",
      "value": 2480,
      "unit": "currency",
      "currency_code": "usd",
      "precision": 2,
      "previous_value": 2310,
      "delta_value": 170,
      "delta_percentage": 7.36
    },
    {
      "key": "churn_rate",
      "label": "Churn Rate",
      "value": 3.2,
      "unit": "percentage",
      "currency_code": null,
      "precision": 2,
      "previous_value": 4.1,
      "delta_value": -0.9,
      "delta_percentage": -21.95
    },
    {
      "key": "ltv",
      "label": "LTV",
      "value": 412,
      "unit": "currency",
      "currency_code": "usd",
      "precision": 2,
      "previous_value": 398,
      "delta_value": 14,
      "delta_percentage": 3.52
    },
    {
      "key": "active_subscriptions_count",
      "label": "Active Subscriptions",
      "value": 182,
      "unit": "count",
      "currency_code": null,
      "precision": 0,
      "previous_value": 176,
      "delta_value": 6,
      "delta_percentage": 3.41
    }
  ]
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid filter shape, unsupported grouping value, or invalid frequency token

GET /admin/subscription-analytics/trends

Returns grouped time-series data for Admin analytics charts. Each series covers one metric key and contains one point per time bucket within the requested range.

created_subscriptions_count is a special-case series:

it is sourced from subscription.created_at
it always returns one UTC day bucket per point
it ignores status, product_id, frequency, and group_by
it zero-fills missing days inside the selected range

Response

object[]

required

Array of trend series, one per metric key.

Show series properties

string

Metric key.

string

Human-readable label.

string

One of currency, percentage, or count.

string | null

Currency code for currency metrics, or null.

number

Decimal precision for display formatting.

object[]

Ordered time-series points. Each point has bucket_start, bucket_end, and value (may be null).

object

required

Resolved filter values.

string

required

Analytics schema version identifier.

string

required

Timestamp when the response was generated.

Response example

{
  "filters": {
    "date_from": "2026-04-01T00:00:00.000Z",
    "date_to": "2026-04-30T23:59:59.999Z",
    "status": ["active"],
    "product_id": [],
    "frequency": [],
    "group_by": "week"
  },
  "metrics_version": "analytics-v1",
  "generated_at": "2026-05-01T10:00:00.000Z",
  "series": [
    {
      "metric": "mrr",
      "label": "MRR",
      "unit": "currency",
      "currency_code": "usd",
      "precision": 2,
      "points": [
        {
          "bucket_start": "2026-03-30T00:00:00.000Z",
          "bucket_end": "2026-04-05T23:59:59.999Z",
          "value": 2280
        },
        {
          "bucket_start": "2026-04-06T00:00:00.000Z",
          "bucket_end": "2026-04-12T23:59:59.999Z",
          "value": 2330
        }
      ]
    },
    {
      "metric": "active_subscriptions_count",
      "label": "Active Subscriptions",
      "unit": "count",
      "currency_code": null,
      "precision": 0,
      "points": [
        {
          "bucket_start": "2026-03-30T00:00:00.000Z",
          "bucket_end": "2026-04-05T23:59:59.999Z",
          "value": 174
        },
        {
          "bucket_start": "2026-04-06T00:00:00.000Z",
          "bucket_end": "2026-04-12T23:59:59.999Z",
          "value": 178
        }
      ]
    },
    {
      "metric": "created_subscriptions_count",
      "label": "Created Subscriptions",
      "unit": "count",
      "currency_code": null,
      "precision": 0,
      "points": [
        {
          "bucket_start": "2026-04-01T00:00:00.000Z",
          "bucket_end": "2026-04-01T23:59:59.999Z",
          "value": 3
        },
        {
          "bucket_start": "2026-04-02T00:00:00.000Z",
          "bucket_end": "2026-04-02T23:59:59.999Z",
          "value": 0
        }
      ]
    }
  ]
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid filter shape, unsupported grouping value, or invalid frequency token

GET /admin/subscription-analytics/export

Returns an export payload aligned with the active analytics filters. The export is synchronous and supports json and csv formats. Rows represent one entry per time bucket.

Additional query parameter

string

Export format. One of json or csv. Defaults to json.

Response

string

required

Resolved export format.

object

required

Resolved filter values.

string

required

Analytics schema version identifier.

string

required

Timestamp when the export was generated.

string

required

Suggested file name for the export.

string

required

MIME type for the export format.

string[]

required

Ordered column names for the export dataset.

object[]

required

Flattened export rows. Each row contains one value per column. Metric cells may be null.

Response example

{
  "format": "json",
  "filters": {
    "date_from": "2026-04-01T00:00:00.000Z",
    "date_to": "2026-04-30T23:59:59.999Z",
    "status": ["active"],
    "product_id": [],
    "frequency": [],
    "group_by": "month"
  },
  "metrics_version": "analytics-v1",
  "generated_at": "2026-05-01T10:00:00.000Z",
  "file_name": "subscription-analytics-2026-05-01.json",
  "content_type": "application/json",
  "columns": [
    "bucket_start",
    "bucket_end",
    "mrr",
    "churn_rate",
    "ltv",
    "active_subscriptions_count"
  ],
  "rows": [
    {
      "bucket_start": "2026-04-01T00:00:00.000Z",
      "bucket_end": "2026-04-30T23:59:59.999Z",
      "mrr": 2480,
      "churn_rate": 3.2,
      "ltv": 412,
      "active_subscriptions_count": 182
    }
  ]
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid filter shape, unsupported grouping value, unsupported export format, or invalid frequency token

POST /admin/subscription-analytics/rebuild

Triggers a manual rebuild of daily analytics snapshots for a historical date range. Reuses the same shared workflow used by scheduled and incremental analytics jobs. Rebuild is day-level idempotent — rerunning the same range is safe.

Body parameters

string

required

ISO datetime start of the rebuild range.

string

required

ISO datetime end of the rebuild range. Maximum manual rebuild window is 365 days.

string

Optional reason for the rebuild, recorded for audit purposes.

Request example

{
  "date_from": "2026-04-01T00:00:00.000Z",
  "date_to": "2026-04-30T23:59:59.999Z",
  "reason": "historical backfill after metrics review"
}

Response

string

required

Rebuild range start.

string

required

Rebuild range end.

number

required

Number of calendar days processed.

number

required

Total subscription records evaluated.

number

required

Snapshot rows created or updated.

number

required

Rows skipped during the rebuild.

string[]

required

Days that could not be processed.

string[]

required

Days where processing failed. Partial failure does not change the HTTP status to 500.

Response example

{
  "date_from": "2026-04-01T00:00:00.000Z",
  "date_to": "2026-04-30T23:59:59.999Z",
  "processed_days": 30,
  "processed_subscriptions": 1240,
  "upserted_rows": 1240,
  "skipped_rows": 0,
  "blocked_days": [],
  "failed_days": []
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid request body or rebuild window exceeds 365 days

Admin API

Store API

Metric keys

Shared filter parameters

GET /admin/subscription-analytics/kpis

Response

Errors

GET /admin/subscription-analytics/trends

Response

Errors

GET /admin/subscription-analytics/export

Additional query parameter

Response

Errors

POST /admin/subscription-analytics/rebuild

Body parameters

Response

Errors

​Metric keys

​Shared filter parameters

​GET /admin/subscription-analytics/kpis

​Response

​Errors

​GET /admin/subscription-analytics/trends

​Response

​Errors

​GET /admin/subscription-analytics/export

​Additional query parameter

​Response

​Errors

​POST /admin/subscription-analytics/rebuild

​Body parameters

​Response

​Errors

Metric keys

Shared filter parameters

GET /admin/subscription-analytics/kpis

Response

Errors

GET /admin/subscription-analytics/trends

Response

Errors

GET /admin/subscription-analytics/export

Additional query parameter

Response

Errors

POST /admin/subscription-analytics/rebuild

Body parameters

Response

Errors