Admin API: subscription analytics endpoints

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

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

Shared filter parameters

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

date_from

string

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

date_to

string

ISO datetime upper bound.

status

string | string[]

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

product_id

string | string[]

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

frequency

string | string[]

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

group_by

string

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

timezone

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

kpis

object[]

required

Array of KPI summaries, one per supported metric key.

Show KPI properties

key

string

Metric key.

label

string

Human-readable label.

value

number | null

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

unit

string

One of currency, percentage, or count.

currency_code

string | null

Currency code for currency metrics, or null.

precision

number

Decimal precision for display formatting.

previous_value

number | null

Value for the prior comparable period.

delta_value

number | null

Absolute change from previous period.

delta_percentage

number | null

Percentage change from previous period.

filters

object

required

Resolved filter values used for the query.

metrics_version

string

required

Analytics schema version identifier.

generated_at

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.

Response

series

object[]

required

Array of trend series, one per metric key.

Show series properties

metric

string

Metric key.

label

string

Human-readable label.

unit

string

One of currency, percentage, or count.

currency_code

string | null

Currency code for currency metrics, or null.

precision

number

Decimal precision for display formatting.

points

object[]

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

filters

object

required

Resolved filter values.

metrics_version

string

required

Analytics schema version identifier.

generated_at

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
        }
      ]
    }
  ]
}

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

format

string

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

Response

format

string

required

Resolved export format.

filters

object

required

Resolved filter values.

metrics_version

string

required

Analytics schema version identifier.

generated_at

string

required

Timestamp when the export was generated.

file_name

string

required

Suggested file name for the export.

content_type

string

required

MIME type for the export format.

columns

string[]

required

Ordered column names for the export dataset.

rows

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

date_from

string

required

ISO datetime start of the rebuild range.

date_to

string

required

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

reason

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

date_from

string

required

Rebuild range start.

date_to

string

required

Rebuild range end.

processed_days

number

required

Number of calendar days processed.

processed_subscriptions

number

required

Total subscription records evaluated.

upserted_rows

number

required

Snapshot rows created or updated.

skipped_rows

number

required

Rows skipped during the rebuild.

blocked_days

string[]

required

Days that could not be processed.

failed_days

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