Track the full history of a subscription

What's new?

We've added a new subscription history 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 to get the history for a subscription. You can filter by action, source, actor, reason, and time, and page through results newest first.

Subscription history isn't a replacement for webhooks. You should use webhooks to tell your app about changes in real time for provisioning and fulfillment, and use subscription history to read the history of a subscription.

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. Entries are returned newest first: a cancellation, an activation, and the original creation.

GET /subscriptions/{subscription_id}/history

Response

{
  "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
    }
  }
}

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 to get started.

Track the full history of a subscription

What's new?

How it works

Entries before history recording began

Example

Next steps

Summary of changes

List subscription history

API keys

Was this page helpful?