> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Track the full history of a subscription

Get a complete chronological record of the changes made to a subscription over its lifetime, so you can see when, why, and who made a change.

---

## What's new?

We've added a new [subscription history](https://developer.paddle.com/api-reference/subscription-history.md) operation to the Paddle API. Use it to retrieve a chronological record of the changes made to a subscription over its lifetime, so you can understand when, why, and who made a change.

## How it works

Paddle records each change to a subscription as a **history entry**. Each entry captures:

- **What** happened: the `action`, like `subscription_created` or `subscription_canceled`.
- **Who** did it: the `actor`, like a customer, a dashboard user, or an API key.
- **Where** it happened: the `source`, like the API, the dashboard, or a checkout.
- **When** it happened: the `occurred_at` timestamp.
- **Why** it happened: the `reason`, for actions where a reason applies.

Each entry also includes a `detail` object. This is a polymorphic object, where the shape depends on the `action`. Changes made in the same request share a `group_id`, so you can group them together.

[List subscription history](https://developer.paddle.com/api-reference/subscription-history/list-subscription-history.md) to get the history for a subscription. You can filter by action, source, actor, reason, and time, and page through results newest first.

{% callout type="info" %}
Subscription history isn't a replacement for [webhooks](https://developer.paddle.com/webhooks.md). You should use webhooks to tell your app about changes in real time for [provisioning and fulfillment](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md), and use subscription history to read the history of a subscription.
{% /callout %}

### Entries before history recording began

For subscriptions that existed before history recording began (June 29, 2026), Paddle automatically creates `subscription_created` and `subscription_canceled` entries and attempts to infer details from the subscription's initial state.

If details can't be inferred, Paddle sets `source` to `unknown` and returns fields that aren't known as `null`.

## Example

This example shows the response from [list subscription history](https://developer.paddle.com/api-reference/subscription-history/list-subscription-history.md). Entries are returned newest first: a cancellation, an activation, and the original creation.

{% api-example method="GET" path="/subscriptions/{subscription_id}/history" %}

```json {% title="Response" collapse=true %}
{
  "data": [
    {
      "id": "subhis_01k0w2m6p8x9y0z1a2b3c4d5e6",
      "group_id": "subhisgrp_01k0w2m6p8x9y0z1a2b3c4d5e6",
      "subscription_id": "sub_01hv959anj4zrw503h2acawb3p",
      "occurred_at": "2024-05-02T11:20:31Z",
      "source": "customer_portal",
      "actor": {
        "type": "customer",
        "id": "ctm_01hv8wt8nffez4p2t6typn4a5j"
      },
      "reason": "customer_request",
      "detail": {
        "action": "subscription_canceled",
        "effective_from": "next_billing_period"
      }
    },
    {
      "id": "subhis_01k0w1f5n7w8x9y0z1a2b3c4d5",
      "group_id": "subhisgrp_01k0w1f5n7w8x9y0z1a2b3c4d5",
      "subscription_id": "sub_01hv959anj4zrw503h2acawb3p",
      "occurred_at": "2024-04-12T12:42:28Z",
      "source": "system",
      "actor": {
        "type": "system",
        "id": null
      },
      "reason": null,
      "detail": {
        "action": "subscription_activated",
        "status": "active",
        "first_billed_at": "2024-04-12T12:42:28Z",
        "next_billed_at": "2024-05-12T12:42:28Z",
        "current_billing_period": {
          "starts_at": "2024-04-12T12:42:28Z",
          "ends_at": "2024-05-12T12:42:28Z"
        },
        "transaction_id": "txn_01h89231k3a1q8mn6p4r5s7t9v"
      }
    },
    {
      "id": "subhis_01k0w0a4m6v7w8x9y0z1a2b3c4",
      "group_id": "subhisgrp_01k0w0a4m6v7w8x9y0z1a2b3c4",
      "subscription_id": "sub_01hv959anj4zrw503h2acawb3p",
      "occurred_at": "2024-04-12T12:42:27Z",
      "source": "checkout",
      "actor": {
        "type": "customer",
        "id": "ctm_01hv8wt8nffez4p2t6typn4a5j"
      },
      "reason": null,
      "detail": {
        "action": "subscription_created",
        "status": "active",
        "collection_mode": "automatic",
        "billing_details": null,
        "customer": null,
        "address": null,
        "business": null,
        "currency_code": "USD",
        "current_billing_period": {
          "starts_at": "2024-04-12T12:42:27Z",
          "ends_at": "2024-05-12T12:42:27Z"
        },
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "items": null,
        "custom_data": null,
        "discount": null,
        "has_payment_method": true
      }
    }
  ],
  "meta": {
    "request_id": "170e71a2-ed13-4f45-b002-45693f5361b4",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/subscriptions/sub_01hv959anj4zrw503h2acawb3p/history?after=subhis_01k0w0a4m6v7w8x9y0z1a2b3c4",
      "has_more": false,
      "estimated_total": 3
    }
  }
}
```

{% /api-example %}

## Next steps

This change is available in version `1` of the Paddle API. It's a non-breaking change, meaning it doesn't impact existing integrations.

Reading subscription history requires the `subscription_history.read` permission on your API key. See the [subscription history overview](https://developer.paddle.com/api-reference/subscription-history.md) to get started.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| GET List subscription history | API operation | added | List subscription history | Returns a paginated, newest-first list of history entries for a subscription, with filters for action, source, actor, reason, and time. |
| `subscription_history.read` | Permission | added | API keys | New permission required to list subscription history. |