Skip to content
Docs
APISign inStart free

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.

GET/api/v1/subscriptions/{id}/events

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

FieldTypeDescription
idsub_… ID

Query parameters

FieldTypeRequiredDescription
limitinteger (1 to 100)No
starting_aftersevt_… IDNo

Response

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

FieldTypeDescription
object"list"
dataarray of object
data[].idsevt_… ID
data[].object"subscription_event"
data[].livemodeboolean
data[].subscriptionIdsub_… ID
data[].customerIdcus_… ID
data[].typeone of 20 values, e.g. created, trial_started, trial_ended (all in the OpenAPI document)
data[].beforeobject or null
data[].afterobject or null
data[].mrrDeltamoney or nullHow this moved monthly recurring revenue.
data[].actorobject
data[].actor.typestring
data[].actor.idstring
data[].actor.viastring or null
data[].atdate-time
has_moreboolean
next_cursorsevt_… 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

CodeHTTP statusWhenWhat to do
resource_not_found404No 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_denied403You 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: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, scope_required, dry_run_not_supported, rate_limited, internal_error.