Subscription metrics · Ownrecord docs

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`	400	`from` isn't before `to`.	Fix the fields listed in `details.issues` and send the request again.
`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: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The last 30 days#

Errors#