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

# Subscription history

Subscription history is a chronological record of the changes to a subscription over its lifetime, including what changed, who did it, and why.

---

Subscription history is a record of the changes that happen to a [subscription](https://developer.paddle.com/api-reference/subscriptions.md) over its lifetime.

Paddle captures each change as a history entry that describes what happened, when it happened, where it came from, who triggered it, and why it happened. You can use subscription history to answer questions like:

- When was this subscription created?
- Why was it canceled?
- Who paused it?
- When did the billing date change?

A subscription history entry holds information like:

- The action that took place, like `subscription_created` or `subscription_canceled`.
- The actor that performed the action, like a customer, a dashboard user, or an API key.
- The source where the action happened, like the API, the dashboard, or a checkout.
- The reason why the action happened, for actions where a reason applies.
- The time the action happened, as `occurred_at`.
- A polymorphic `detail` object that holds information specific to the action.

History entries are read-only. Paddle records them automatically as actions happen on a subscription, so you can't create, update, or delete them.

## Subscription history groups

A single API request can make several changes to a subscription at once. For example, [upgrading or downgrading a subscription](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) typically results in two history entries: one for adding the new item, and one for removing the old item.

Paddle records each change as its own history entry, but entries that come from the same request share a `group_id`, prefixed with `subhisgrp_`. You can use the `group_id` to group related changes together.

## Actions and detail

The `action` field tells you what changed. It also works as a discriminator for the `detail` object: the shape of `detail` depends on the value of `action`.

For example, a `subscription_created` entry includes a snapshot of the subscription's initial state, like its status, items, and currency, while a `subscription_canceled` entry includes whether the cancellation took effect immediately or at the next billing period.

## Entries before history recording began

Paddle began recording subscription history on June 29, 2026. For subscriptions that existed before then, 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`.

## Relation to notifications and events

When something notable occurs in your system, Paddle creates an [event entity](https://developer.paddle.com/api-reference/events.md) with information about what happened. For events, Paddle can send a [webhook notification](https://developer.paddle.com/api-reference/notifications.md) to your server with the event payload as JSON.

Subscription history is a record of the changes that happen to a subscription over its lifetime. It's a stored, queryable record of past changes that you read on demand.

History entries don't map one-to-one to webhook notifications. You should use [webhooks](https://developer.paddle.com/webhooks.md) to tell your app about changes in real time for [provisioning and fulfillment](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md).