# List a subscription's history

> The subscriptions.events.list operation: GET /api/v1/subscriptions/{id}/events in the REST API and the subscriptions_events_list tool in the MCP server.

Lists a subscription's history, newest first: creation, trial, activation, plan and quantity changes,
discounts, scheduled changes, pauses, cancellations, renewals and payment problems. Each entry has what changed
(`before`, `after`), how it moved monthly recurring revenue (`mrrDelta`), who did it and when.

Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page).

## At a glance

- **REST:** `GET /api/v1/subscriptions/{id}/events`
- **MCP tool:** `subscriptions_events_list`
- **Operation ID:** `subscriptions.events.list`
- **Scope:** Brand
- **Permission:** `subscriptions:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `subscriptions:read` scope
- **Since:** M5

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `sub_…` ID |             |

### Query parameters

| Field            | Type               | Required | Description |
| ---------------- | ------------------ | -------- | ----------- |
| `limit`          | integer (1 to 100) | No       |             |
| `starting_after` | `sevt_…` ID        | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                   | Type                                                                                           | Description                               |
| ----------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `object`                | `"list"`                                                                                       |                                           |
| `data`                  | array of object                                                                                |                                           |
| `data[].id`             | `sevt_…` ID                                                                                    |                                           |
| `data[].object`         | `"subscription_event"`                                                                         |                                           |
| `data[].livemode`       | boolean                                                                                        |                                           |
| `data[].subscriptionId` | `sub_…` ID                                                                                     |                                           |
| `data[].customerId`     | `cus_…` ID                                                                                     |                                           |
| `data[].type`           | one of 20 values, e.g. `created`, `trial_started`, `trial_ended` (all in the OpenAPI document) |                                           |
| `data[].before`         | object or null                                                                                 |                                           |
| `data[].after`          | object or null                                                                                 |                                           |
| `data[].mrrDelta`       | money or null                                                                                  | How this moved monthly recurring revenue. |
| `data[].actor`          | object                                                                                         |                                           |
| `data[].actor.type`     | string                                                                                         |                                           |
| `data[].actor.id`       | string                                                                                         |                                           |
| `data[].actor.via`      | string or null                                                                                 |                                           |
| `data[].at`             | date-time                                                                                      |                                           |
| `has_more`              | boolean                                                                                        |                                           |
| `next_cursor`           | `sevt_…` ID or null                                                                            |                                           |

## Examples

### The latest changes

```http
GET /api/v1/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf47z5/events?limit=2
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "sevt_01m4tx5nj8emwbyf7y9vcf47zg",
      "object": "subscription_event",
      "livemode": false,
      "subscriptionId": "sub_01m4tx5nj8emwbyf7y9vcf47z5",
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47z4",
      "type": "upgraded",
      "before": {
        "items": [
          {
            "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
            "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y2",
            "quantity": 3
          }
        ]
      },
      "after": {
        "items": [
          {
            "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
            "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y3",
            "quantity": 3
          }
        ],
        "effective": "now",
        "prorationBehavior": "always_invoice",
        "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47zn"
      },
      "mrrDelta": {
        "amount": "60000000",
        "currency": "EUR"
      },
      "actor": {
        "type": "user",
        "id": "usr_01m4tx5nj8emwbyf7y9vcf47zk",
        "via": "console"
      },
      "at": "2026-10-20T09:00:00.000Z"
    },
    {
      "id": "sevt_01m4tx5nj8emwbyf7y9vcf47zh",
      "object": "subscription_event",
      "livemode": false,
      "subscriptionId": "sub_01m4tx5nj8emwbyf7y9vcf47z5",
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47z4",
      "type": "created",
      "before": null,
      "after": {
        "status": "active"
      },
      "mrrDelta": {
        "amount": "87000000",
        "currency": "EUR"
      },
      "actor": {
        "type": "user",
        "id": "usr_01m4tx5nj8emwbyf7y9vcf47zk",
        "via": "console"
      },
      "at": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                             | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No subscription with this ID is visible to the request.          | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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), [`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).