Subscription history

Subscription history is a record of the changes that happen to a subscription 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 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 with information about what happened. For events, Paddle can send a webhook notification 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 to tell your app about changes in real time for provisioning and fulfillment.