> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reorderjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Analytics gives operators a reporting dashboard for recurring-commerce KPIs, trends, and exports — built primarily on daily subscription snapshots.

Analytics is a reporting layer that aggregates data from across the plugin and exposes it as KPI cards, trend charts, and exportable datasets. It is read-only — it does not own or modify subscription, renewal, dunning, or cancellation state. Instead, it derives its outputs from those domains and precomputes daily snapshots for fast, consistent reads.

## KPI cards

The Analytics page shows four key performance indicators for the selected date range and filters:

| KPI                      | What it measures                                                        |
| ------------------------ | ----------------------------------------------------------------------- |
| **MRR**                  | Monthly-normalized recurring revenue from active subscriptions          |
| **Churn Rate**           | Canceled subscriptions in the period divided by the average active base |
| **LTV**                  | Derived as `MRR / churn_rate` — null when either input is unavailable   |
| **Active Subscriptions** | Count of subscriptions currently in `active` status                     |

`MRR` and `LTV` are currency-aware. If your dataset spans multiple currencies without normalization, both values will be shown as unavailable rather than producing a misleading total. `Churn Rate` and `Active Subscriptions` are currency-independent.

## Filters

All KPI cards, most trend series, and exports respond to the same set of filters:

* **Date range** — `date_from` and `date_to`, both inclusive
* **Status** — filter by subscription lifecycle status
* **Product** — filter by product ID
* **Frequency** — filter by billing cadence (e.g. weekly, monthly, yearly)
* **Group by** — bucket trend data by `day`, `week`, or `month`

All date calculations use UTC.

## Trend chart

The trend chart visualizes one metric over the selected date range.

* `MRR`, `Churn`, and `LTV` are grouped by the selected `group_by` value.
* `created_subscriptions_count` is a special-case trend sourced directly from `subscription.created_at`.
* The created-subscriptions trend always renders daily UTC buckets and zero-fills missing days inside the range.

## Export

The Analytics page supports on-demand export of the currently visible reporting slice:

| Format | Behavior                                                                    |
| ------ | --------------------------------------------------------------------------- |
| `CSV`  | Flat rows matching the active filters and bucket semantics                  |
| `JSON` | Structured export payload with the same column ordering as the API response |

Export is synchronous — it runs on demand and always reflects the currently active filters.

## How snapshots work

Analytics precomputes one snapshot row per subscription per day. These daily snapshots power KPI queries, the snapshot-backed trend series, and exports — the dashboard does not recompute everything live from operational data on each request.

### Implemented exception

The created-subscriptions trend does not come from `subscription_metrics_daily`.

It is read directly from `subscription.created_at` because the required business question is simpler: how many subscriptions were created on each day in the selected range.

Snapshots are rebuilt automatically by a daily scheduled job, with a short lookback window to self-heal recent changes. They can also be triggered incrementally after significant domain events such as subscription resumes, cancellation finalizations, or renewal executions that affect revenue data.

<Note>
  If the analytics dashboard shows stale data after a significant operational change, a manual rebuild can be triggered from the Admin. The rebuild covers any date range and produces the same output as the scheduled job.
</Note>