PApaddlehq
Subscription history

List history for a subscription

Changed on

Returns a paginated list of history entries for a subscription. Use the query parameters to filter and page through results.

Subscription history records the changes made to a subscription over its lifetime, so you can see what changed, when it happened, where it originated, and who made the change. Each change is a separate history entry, and some entries also include a reason.

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.

History entries are ordered by newest first by default (id in descending order).

get/subscriptions/{subscription_id}/history

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

Path parameters

subscription_idstring required

Unique Paddle ID for this subscription entity, prefixed with sub_.

Example:sub_01h04vsc0qhwtsbsxh3422wjs4

Query parameters

actionSubscriptionHistoryActionQuery[]

Return history entries that match the specified action. Use a comma-separated list to specify multiple action values.

sourceSubscriptionHistorySourceQuery[]

Return history entries that match the specified source. Use a comma-separated list to specify multiple source values.

actor_typeSubscriptionHistoryActorTypeQuery[]

Return history entries that match the specified actor type. Use a comma-separated list to specify multiple actor type values.

actor_idstring[]

Return history entries that match the specified actor ID. Use a comma-separated list to specify multiple actor ID values. Only applicable if actor_type is also selected.

reasonSubscriptionHistoryReasonQuery[]

Return history entries that match the specified reason. Use a comma-separated list to specify multiple reason values.

occurred_atstring

Return entities that occurred at a specific time. Use [LTE] (less than or equal to) or [GTE] (greater than or equal to) operators with an RFC 3339 datetime string. For example, occurred_at[LTE]=2023-04-18T17:03:26 or occurred_at[GTE]=2023-04-18T17:03:26.

afterstring

Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.

per_pageinteger

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

order_bystring

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[DESC].

Valid fields for ordering: id.

Headers

Skip-Countstring

Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response

The request has succeeded.

Example response

{
  "data": [
    {
      "id": "subhis_01kagxfkdpvsdvnm7xw4avwvsp",
      "group_id": "subhisgrp_01kagxffkcme9fhd6srqgkmssd",
      "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
      "occurred_at": "2024-10-12T07:20:50.52Z",
      "detail": {
        "first_billed_at": "2024-10-12T07:20:50.52Z",
        "next_billed_at": "2024-10-12T07:20:50.52Z",
        "current_billing_period": {
          "starts_at": "2024-10-12T07:20:50.52Z",
          "ends_at": "2024-10-12T07:20:50.52Z"
        },
        "transaction_id": "txn_01h04vsbhqc62t8hmd4z3b578c"
      }
    }
  ],
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355",
    "pagination": {
      "estimated_total": 999
    }
  }
}

Changes

  • v14f35a8c6ea4dRevision changes
    • breaking

      for the query request parameter order_by, default value was changed from occurred_at[DESC] to id[DESC]

    • breaking

      added to the ////////////// response property oneOf list for the response status

    • breaking

      added to the ////////////////// response property oneOf list for the response status

    • breaking

      added to the //////////////// response property oneOf list for the response status

    • breaking

      added to the /////////////// response property oneOf list for the response status

    • breaking

      added to the ///////////// response property oneOf list for the response status

    • breaking

      added to the /////////////// response property oneOf list for the response status

    • breaking

      added to the ///////////// response property oneOf list for the response status

    • breaking

      added to the /////////////// response property oneOf list for the response status

    • breaking

      added to the ///////////// response property oneOf list for the response status

    • breaking

      added to the ///////////////// response property oneOf list for the response status

    • breaking

      added to the /////////////// response property oneOf list for the response status

    • breaking

      added to the ////////////// response property oneOf list for the response status

    • warning

      added the new eu_withdrawal enum value to the /////// response property for the response status

    • info

      added the enum value eu_withdrawal to the property items/ of the query request parameter reason

  • v1e1ac347eb3c5Revision changes
    • info

      endpoint added