# Subscription metrics

> The subscriptions.metrics operation: GET /api/v1/subscription_metrics in the REST API and the subscriptions_metrics tool in the MCP server.

The brand's monthly recurring revenue (MRR) per currency in the request's mode, from the subscriptions'
history: MRR at the window's start and end, and what moved it in between: new (subscriptions that started
paying), reactivation (resumed or recovered), expansion (upgrades, more seats), contraction (downgrades, fewer
seats) and churn (canceled, paused, expired unpaid), with the churn rate (churned MRR / MRR at the start).

MRR counts active and past-due subscriptions' licensed items at their monthly amount (a year is 12 months),
before discounts and tax; trials, paused and ended subscriptions don't count. The window is `[from, to)`,
by default the last 30 days.

## At a glance

- **REST:** `GET /api/v1/subscription_metrics`
- **MCP tool:** `subscriptions_metrics`
- **Operation ID:** `subscriptions.metrics`
- **Scope:** Brand
- **Permission:** `subscriptions:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `subscriptions:read` scope
- **Since:** M5

## Request

### Query parameters

| Field  | Type      | Required | Description                                        |
| ------ | --------- | -------- | -------------------------------------------------- |
| `from` | date-time | No       | The window's start (default: 30 days before `to`). |
| `to`   | date-time | No       | The window's end (default: now).                   |

## Response

`200 OK` with a JSON object:

| Field                          | Type                     | Description                                                                 |
| ------------------------------ | ------------------------ | --------------------------------------------------------------------------- |
| `object`                       | `"subscription_metrics"` |                                                                             |
| `livemode`                     | boolean                  |                                                                             |
| `from`                         | date-time                |                                                                             |
| `to`                           | date-time                |                                                                             |
| `currencies`                   | array of object          |                                                                             |
| `currencies[].currency`        | string                   |                                                                             |
| `currencies[].mrr`             | money                    | Monthly recurring revenue at `to`.                                          |
| `currencies[].startMrr`        | money                    | Monthly recurring revenue at `from`.                                        |
| `currencies[].newMrr`          | money                    |                                                                             |
| `currencies[].reactivationMrr` | money                    |                                                                             |
| `currencies[].expansionMrr`    | money                    |                                                                             |
| `currencies[].contractionMrr`  | money                    |                                                                             |
| `currencies[].churnedMrr`      | money                    |                                                                             |
| `currencies[].netNewMrr`       | money                    |                                                                             |
| `currencies[].churnRatePpm`    | string                   | Churned MRR / MRR at `from`, in parts per million (25000 = 2.5%).           |
| `truncated`                    | boolean                  | True when the history was too long to read whole (the figures are partial). |

## Examples

### The last 30 days

```http
GET /api/v1/subscription_metrics
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "subscription_metrics",
  "livemode": false,
  "from": "2026-09-20T09:00:00.000Z",
  "to": "2026-10-20T09:00:00.000Z",
  "currencies": [
    {
      "currency": "EUR",
      "mrr": {
        "amount": "12450000000",
        "currency": "EUR"
      },
      "startMrr": {
        "amount": "11800000000",
        "currency": "EUR"
      },
      "newMrr": {
        "amount": "870000000",
        "currency": "EUR"
      },
      "reactivationMrr": {
        "amount": "0",
        "currency": "EUR"
      },
      "expansionMrr": {
        "amount": "240000000",
        "currency": "EUR"
      },
      "contractionMrr": {
        "amount": "60000000",
        "currency": "EUR"
      },
      "churnedMrr": {
        "amount": "400000000",
        "currency": "EUR"
      },
      "netNewMrr": {
        "amount": "650000000",
        "currency": "EUR"
      },
      "churnRatePpm": "33898"
    }
  ],
  "truncated": false
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                             | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | `from` isn't before `to`.                                        | Fix the fields listed in `details.issues` and send the request again.           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't see this brand's subscriptions (`subscriptions:read`). | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).