--- title: "List history for a subscription" method: GET path: "/subscriptions/{subscription_id}/history" tags: ["Subscription history"] --- # List history for a subscription `GET /subscriptions/{subscription_id}/history` ## Request - Base URL: `https://sandbox-api.paddle.com` - URL: `https://sandbox-api.paddle.com/subscriptions/{subscription_id}/history` - Auth: HTTP bearer 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). ## Path parameters - `subscription_id` string, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`. ## Query parameters - `action` SubscriptionHistoryActionQuery[] - `source` SubscriptionHistorySourceQuery[] - `actor_type` SubscriptionHistoryActorTypeQuery[] - `actor_id` string[] - `reason` SubscriptionHistoryReasonQuery[] - `occurred_at` string - `after` string - `per_page` integer - `order_by` string ## Headers - `Skip-Count` string ## Response `200` The request has succeeded. - object - `data` SubscriptionHistory[], required - `id` string, required: Unique Paddle ID for this subscription history entry, prefixed with `subhis_`. - `group_id` string, required: Unique Paddle ID for this subscription history group. History entries that occurred at the same time, as part of the same request, share the same group ID. Prefixed with `subhisgrp_`. - `subscription_id` string, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`. - `occurred_at` string, date-time, required: RFC 3339 datetime string. - `source` 'system' | 'api' | 'dashboard' | 'customer_portal' | 'support_bot' | 'retain' | 'checkout' | 'external_provider' | 'paddle_classic' | 'unknown', required: Where the entry originated from. - `actor` Actor, required: Details about the actor that performed an action. - `type` 'customer' | 'user' | 'api_key' | 'paddle_staff' | 'publisher' | 'system', required: The type of actor that performed this action. - `id` string, nullable, required: The ID of the actor in relation to the `type`. `null` where the type of actor doesn't have an ID. - `reason` 'cardless_trial_ended' | 'import_issue' | 'missing_consent' | 'seller_request' | 'customer_request' | 'chargeback' | 'eu_withdrawal', required: Why the entry was created. Only applicable to certain actions. - `detail` union, required - object: Details specific to `subscription_activated` actions. - `action` 'subscription_activated', required: What happened on the subscription. - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required: Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - `first_billed_at` string, date-time, required: RFC 3339 datetime string. - `next_billed_at` string, date-time, required: RFC 3339 datetime string. - `current_billing_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_address_updated` actions. - `action` 'subscription_address_updated', required: What happened on the subscription. - `address` Address, required: Represents an address entity. - `id` string, required: Unique Paddle ID for this address entity, prefixed with `add_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `description` string, required: Memorable description for this address. - `first_line` string, required: First line of this address. - `second_line` string, required: Second line of this address. - `city` string, required: City of this address. - `postal_code` string, required: ZIP or postal code of this address. Required for some countries. - `region` string, required: State, county, or region of this address. - `country_code` union, required - 'AD' | 'AE' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BZ' | 'CA' | 'CC' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RW' | 'SA' | 'SB' | 'SC' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SR' | 'ST' | 'SV' | 'SX' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YT' | 'ZA' | 'ZM': Two-letter code for a country that Paddle supports sales to. Typically an ISO 3166-1 alpha-2 code, though Paddle uses a small number of codes that ISO doesn't currently assign. - 'AF' | 'AQ' | 'AN' | 'BY' | 'CD' | 'CF' | 'CU' | 'CS' | 'HT' | 'IR' | 'KP' | 'LY' | 'ML' | 'MM' | 'NI' | 'RU' | 'SO' | 'SS' | 'SD' | 'SY' | 'VE' | 'YE' | 'ZW': Two-letter code for a country that Paddle doesn't support sales to. Typically an ISO 3166-1 alpha-2 code, though Paddle uses a small number of codes that ISO doesn't currently assign. - `custom_data` CustomData, required: Your own structured key-value data. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - object: Details specific to `subscription_billing_cycle_updated` actions. - `action` 'subscription_billing_cycle_updated', required: What happened on the subscription. - `billing_cycle` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `current_billing_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `next_billed_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_billing_date_updated` actions. - `action` 'subscription_billing_date_updated', required: What happened on the subscription. - `next_billed_at` string, date-time, required: RFC 3339 datetime string. - `current_billing_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - `proration_billing_mode` 'prorated_immediately' | 'prorated_next_billing_period' | 'full_immediately' | 'full_next_billing_period' | 'do_not_bill', required: How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing. For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used. - object: Details specific to `subscription_billing_details_updated` actions. - `action` 'subscription_billing_details_updated', required: What happened on the subscription. - `billing_details` BillingDetails, required: Details for invoicing. Required if `collection_mode` is `manual`. - `enable_checkout` boolean, required: Whether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to `false`. - `purchase_order_number` string, required: Customer purchase order number. Appears on invoice documents. - `additional_information` string, nullable, required: Notes or other information to include on this invoice. Appears on invoice documents. - `payment_terms` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - object: Details specific to `subscription_business_added` actions. - `action` 'subscription_business_added', required: What happened on the subscription. - `business` Business, required: Represents a business entity. - `id` string, required: Unique Paddle ID for this business entity, prefixed with `biz_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `company_number` string, nullable, required: Company number for this business. - `tax_identifier` string, nullable, required: Tax or VAT Number for this business. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `contacts` BusinessContactsItem[], required: List of contacts related to this business, typically used for sending invoices. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - object: Details specific to `subscription_business_removed` actions. - `action` 'subscription_business_removed', required: What happened on the subscription. - `business` Business, required: Represents a business entity. - `id` string, required: Unique Paddle ID for this business entity, prefixed with `biz_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `company_number` string, nullable, required: Company number for this business. - `tax_identifier` string, nullable, required: Tax or VAT Number for this business. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `contacts` BusinessContactsItem[], required: List of contacts related to this business, typically used for sending invoices. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - object: Details specific to `subscription_business_updated` actions. - `action` 'subscription_business_updated', required: What happened on the subscription. - `business` Business, required: Represents a business entity. - `id` string, required: Unique Paddle ID for this business entity, prefixed with `biz_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `company_number` string, nullable, required: Company number for this business. - `tax_identifier` string, nullable, required: Tax or VAT Number for this business. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `contacts` BusinessContactsItem[], required: List of contacts related to this business, typically used for sending invoices. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - object: Details specific to `subscription_canceled` actions. - `action` 'subscription_canceled', required: What happened on the subscription. - `effective_from` 'immediately' | 'next_billing_period', required: When the subscription cancellation took effect. - object: Details specific to `subscription_collection_mode_updated` actions. - `action` 'subscription_collection_mode_updated', required: What happened on the subscription. - `collection_mode` 'automatic' | 'manual', required: How payment is collected. `automatic` for checkout, `manual` for invoices. - object: Details specific to `subscription_consent_requirement_granted` actions. - `action` 'subscription_consent_requirement_granted', required: What happened on the subscription. - `consent_requirement` SubscriptionConsentRequirement, required: Represents a specific condition under which explicit customer consent is, or was, mandated for a subscription renewal. - `id` string, required: Unique Paddle ID for this subscription consent requirement entity, prefixed with `subconreq_`. - `requirement` 'trial_ending' | 'introductory_discount_ending', required: Type of consent required for successful renewal. - `status` 'pending' | 'granted' | 'voided', required: Status of this consent requirement. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `consent_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `granted_at` string, date-time, required: RFC 3339 datetime string. - `voided_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_created` actions. - `action` 'subscription_created', required: What happened on the subscription. - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required: Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - `collection_mode` 'automatic' | 'manual', required: How payment is collected. `automatic` for checkout, `manual` for invoices. - `billing_details` BillingDetails, required: Details for invoicing. Required if `collection_mode` is `manual`. - `enable_checkout` boolean, required: Whether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to `false`. - `purchase_order_number` string, required: Customer purchase order number. Appears on invoice documents. - `additional_information` string, nullable, required: Notes or other information to include on this invoice. Appears on invoice documents. - `payment_terms` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `customer` Customer, required: Represents a customer entity. - `id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `marketing_consent` boolean, required: Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `locale` string, required: Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `address` Address, required: Represents an address entity. - `id` string, required: Unique Paddle ID for this address entity, prefixed with `add_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `description` string, required: Memorable description for this address. - `first_line` string, required: First line of this address. - `second_line` string, required: Second line of this address. - `city` string, required: City of this address. - `postal_code` string, required: ZIP or postal code of this address. Required for some countries. - `region` string, required: State, county, or region of this address. - `country_code` union, required - 'AD' | 'AE' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BZ' | 'CA' | 'CC' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RW' | 'SA' | 'SB' | 'SC' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SR' | 'ST' | 'SV' | 'SX' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YT' | 'ZA' | 'ZM': Two-letter code for a country that Paddle supports sales to. Typically an ISO 3166-1 alpha-2 code, though Paddle uses a small number of codes that ISO doesn't currently assign. - 'AF' | 'AQ' | 'AN' | 'BY' | 'CD' | 'CF' | 'CU' | 'CS' | 'HT' | 'IR' | 'KP' | 'LY' | 'ML' | 'MM' | 'NI' | 'RU' | 'SO' | 'SS' | 'SD' | 'SY' | 'VE' | 'YE' | 'ZW': Two-letter code for a country that Paddle doesn't support sales to. Typically an ISO 3166-1 alpha-2 code, though Paddle uses a small number of codes that ISO doesn't currently assign. - `custom_data` CustomData, required: Your own structured key-value data. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `business` Business, required: Represents a business entity. - `id` string, required: Unique Paddle ID for this business entity, prefixed with `biz_`. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `company_number` string, nullable, required: Company number for this business. - `tax_identifier` string, nullable, required: Tax or VAT Number for this business. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `contacts` BusinessContactsItem[], required: List of contacts related to this business, typically used for sending invoices. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `current_billing_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `billing_cycle` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `items` SubscriptionHistoryDetailItem[], nullable, required: Items on the subscription when it was created. - `price` Price, required: Represents a price entity. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `description` string, required: Internal description for this price, not shown to customers. Typically notes for your team. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `name` string, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` Duration, required - … - `trial_period` PriceTrialDuration, required - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - … - `unit_price_overrides` UnitPriceOverride[], required: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. - … - `quantity` PriceQuantity, required - … - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `quantity` integer, required: Quantity of the item on the subscription at the time of the history entry. - `custom_data` CustomData, required: Your own structured key-value data. - `discount` SubscriptionHistoryDiscount, required: Details of a discount on a subscription at the time of a history entry. - `discount` Discount, required: Represents a discount entity. - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `description` string, required: Short description for this discount for your reference. Not shown to customers. - `enabled_for_checkout` boolean, required: Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). - `code` string, required: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive. - `type` 'flat' | 'flat_per_seat' | 'percentage', required: Type of discount. Determines how this discount impacts the checkout or transaction total. - `mode` 'standard' | 'custom', required: Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. - `amount` string, required: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `recur` boolean, required: Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). - `maximum_recurring_intervals` integer, nullable, required: Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. - `usage_limit` integer, nullable, required: Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times. Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against `times_used` at that moment. As `times_used` only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows. - `restrict_to` DiscountRestrictTo[], nullable, required: Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `custom_data` CustomData, required: Your own structured key-value data. - `times_used` integer, required: How many times this discount has been redeemed. Automatically incremented by Paddle. Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Incremented when a transaction completes, rather than when a discount is applied to a checkout. See `usage_limit` for how this affects enforcement of the limit. - `discount_group_id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `type` 'recurring' | 'one-off', required: The type of discount. - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `has_payment_method` boolean, nullable, required: Whether the subscription had a payment method when it was created. `null` if this couldn't be determined. - object: Details specific to `subscription_currency_updated` actions. - `action` 'subscription_currency_updated', required: What happened on the subscription. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - object: Details specific to `subscription_custom_data_updated` actions. - `action` 'subscription_custom_data_updated', required: What happened on the subscription. - `custom_data` CustomData, required: Your own structured key-value data. - object: Details specific to `subscription_customer_updated` actions. - `action` 'subscription_customer_updated', required: What happened on the subscription. - `customer` Customer, required: Represents a customer entity. - `id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `name` string, required: Full name. - `email` string, email, required: Email address for this entity. - `marketing_consent` boolean, required: Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `locale` string, required: Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - object: Details specific to `subscription_discount_added` actions. - `action` 'subscription_discount_added', required: What happened on the subscription. - `discount` SubscriptionHistoryDiscount, required: Details of a discount on a subscription at the time of a history entry. - `discount` Discount, required: Represents a discount entity. - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `description` string, required: Short description for this discount for your reference. Not shown to customers. - `enabled_for_checkout` boolean, required: Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). - `code` string, required: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive. - `type` 'flat' | 'flat_per_seat' | 'percentage', required: Type of discount. Determines how this discount impacts the checkout or transaction total. - `mode` 'standard' | 'custom', required: Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. - `amount` string, required: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `recur` boolean, required: Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). - `maximum_recurring_intervals` integer, nullable, required: Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. - `usage_limit` integer, nullable, required: Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times. Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against `times_used` at that moment. As `times_used` only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows. - `restrict_to` DiscountRestrictTo[], nullable, required: Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `custom_data` CustomData, required: Your own structured key-value data. - `times_used` integer, required: How many times this discount has been redeemed. Automatically incremented by Paddle. Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Incremented when a transaction completes, rather than when a discount is applied to a checkout. See `usage_limit` for how this affects enforcement of the limit. - `discount_group_id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `type` 'recurring' | 'one-off', required: The type of discount. - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_discount_expired` actions. Recorded when a discount is no longer eligible — for example, when the maximum number of billing periods for the discount has been reached. - `action` 'subscription_discount_expired', required: What happened on the subscription. - `discount` SubscriptionHistoryDiscount, required: Details of a discount on a subscription at the time of a history entry. - `discount` Discount, required: Represents a discount entity. - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `description` string, required: Short description for this discount for your reference. Not shown to customers. - `enabled_for_checkout` boolean, required: Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). - `code` string, required: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive. - `type` 'flat' | 'flat_per_seat' | 'percentage', required: Type of discount. Determines how this discount impacts the checkout or transaction total. - `mode` 'standard' | 'custom', required: Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. - `amount` string, required: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `recur` boolean, required: Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). - `maximum_recurring_intervals` integer, nullable, required: Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. - `usage_limit` integer, nullable, required: Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times. Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against `times_used` at that moment. As `times_used` only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows. - `restrict_to` DiscountRestrictTo[], nullable, required: Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `custom_data` CustomData, required: Your own structured key-value data. - `times_used` integer, required: How many times this discount has been redeemed. Automatically incremented by Paddle. Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Incremented when a transaction completes, rather than when a discount is applied to a checkout. See `usage_limit` for how this affects enforcement of the limit. - `discount_group_id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `type` 'recurring' | 'one-off', required: The type of discount. - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_discount_removed` actions. - `action` 'subscription_discount_removed', required: What happened on the subscription. - `discount` SubscriptionHistoryDiscount, required: Details of a discount on a subscription at the time of a history entry. - `discount` Discount, required: Represents a discount entity. - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `description` string, required: Short description for this discount for your reference. Not shown to customers. - `enabled_for_checkout` boolean, required: Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). - `code` string, required: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive. - `type` 'flat' | 'flat_per_seat' | 'percentage', required: Type of discount. Determines how this discount impacts the checkout or transaction total. - `mode` 'standard' | 'custom', required: Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. - `amount` string, required: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `recur` boolean, required: Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). - `maximum_recurring_intervals` integer, nullable, required: Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. - `usage_limit` integer, nullable, required: Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times. Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against `times_used` at that moment. As `times_used` only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows. - `restrict_to` DiscountRestrictTo[], nullable, required: Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `custom_data` CustomData, required: Your own structured key-value data. - `times_used` integer, required: How many times this discount has been redeemed. Automatically incremented by Paddle. Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. Incremented when a transaction completes, rather than when a discount is applied to a checkout. See `usage_limit` for how this affects enforcement of the limit. - `discount_group_id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `type` 'recurring' | 'one-off', required: The type of discount. - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_item_added` actions. - `action` 'subscription_item_added', required: What happened on the subscription. - `price` Price, required: Represents a price entity. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `description` string, required: Internal description for this price, not shown to customers. Typically notes for your team. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `name` string, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `trial_period` PriceTrialDuration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `requires_payment_method` boolean, required: Whether this price requires a payment method (`true`) or not (`false`) when trialing. If `false`, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial." - `unit_price` MoneyOptionalCurrency: A representation of monetary value unformatted in the lowest denomination with optional currency code. - … - `unit_price_overrides` PriceTrialUnitPriceOverride[]: List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries. - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - `amount` string, required: Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `unit_price_overrides` UnitPriceOverride[], required: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. - `country_codes` CountryCode[], required: Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price. - … - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - … - `quantity` PriceQuantity, required - `minimum` integer, required: Minimum quantity of the product related to this price that can be bought. Required if `maximum` set. - `maximum` integer, required: Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `quantity` integer, required: Quantity of the item on the subscription after being added. - `update_summary` SubscriptionHistoryItemUpdateSummary, required: Summary of a quantitative change to an item on a subscription, including the direction and magnitude of the change. - `quantity_delta` integer, required: Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed). - `proration_billing_mode` 'prorated_immediately' | 'prorated_next_billing_period' | 'full_immediately' | 'full_next_billing_period' | 'do_not_bill', required: How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing. For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used. - `on_payment_failure` 'prevent_change' | 'apply_change', required: How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_item_quantity_updated` actions. - `action` 'subscription_item_quantity_updated', required: What happened on the subscription. - `price` Price, required: Represents a price entity. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `description` string, required: Internal description for this price, not shown to customers. Typically notes for your team. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `name` string, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `trial_period` PriceTrialDuration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `requires_payment_method` boolean, required: Whether this price requires a payment method (`true`) or not (`false`) when trialing. If `false`, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial." - `unit_price` MoneyOptionalCurrency: A representation of monetary value unformatted in the lowest denomination with optional currency code. - … - `unit_price_overrides` PriceTrialUnitPriceOverride[]: List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries. - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - `amount` string, required: Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `unit_price_overrides` UnitPriceOverride[], required: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. - `country_codes` CountryCode[], required: Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price. - … - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - … - `quantity` PriceQuantity, required - `minimum` integer, required: Minimum quantity of the product related to this price that can be bought. Required if `maximum` set. - `maximum` integer, required: Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `quantity` integer, required: Total quantity of the item on the subscription after the change. - `update_summary` SubscriptionHistoryItemUpdateSummary, required: Summary of a quantitative change to an item on a subscription, including the direction and magnitude of the change. - `quantity_delta` integer, required: Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed). - `proration_billing_mode` 'prorated_immediately' | 'prorated_next_billing_period' | 'full_immediately' | 'full_next_billing_period' | 'do_not_bill', required: How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing. For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used. - `on_payment_failure` 'prevent_change' | 'apply_change', required: How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_item_removed` actions. - `action` 'subscription_item_removed', required: What happened on the subscription. - `price` Price, required: Represents a price entity. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `description` string, required: Internal description for this price, not shown to customers. Typically notes for your team. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `name` string, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` Duration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `trial_period` PriceTrialDuration, required - `interval` 'day' | 'week' | 'month' | 'year', required - `frequency` integer, required: Amount of time. - `requires_payment_method` boolean, required: Whether this price requires a payment method (`true`) or not (`false`) when trialing. If `false`, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial." - `unit_price` MoneyOptionalCurrency: A representation of monetary value unformatted in the lowest denomination with optional currency code. - … - `unit_price_overrides` PriceTrialUnitPriceOverride[]: List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries. - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - `amount` string, required: Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code. - `unit_price_overrides` UnitPriceOverride[], required: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. - `country_codes` CountryCode[], required: Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price. - … - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - … - `quantity` PriceQuantity, required - `minimum` integer, required: Minimum quantity of the product related to this price that can be bought. Required if `maximum` set. - `maximum` integer, required: Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string: Reference or identifier for this entity from the provider where it was imported from. - `imported_from` string, required: Name of the platform or provider where this entity was imported from. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `quantity` integer, required: Quantity of the item on the subscription after the removal. Always `0` since the item no longer exists on the subscription. - `update_summary` SubscriptionHistoryItemUpdateSummary, required: Summary of a quantitative change to an item on a subscription, including the direction and magnitude of the change. - `quantity_delta` integer, required: Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed). - `proration_billing_mode` 'prorated_immediately' | 'prorated_next_billing_period' | 'full_immediately' | 'full_next_billing_period' | 'do_not_bill', required: How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing. For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used. - `on_payment_failure` 'prevent_change' | 'apply_change', required: How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_one_off_charge_applied` actions. - `action` 'subscription_one_off_charge_applied', required: What happened on the subscription. - `effective_from` 'immediately' | 'next_billing_period', required: When the customer was or will be billed for the one-off charge. - `items` SubscriptionHistoryDetailItem[], required: Items that were charged as part of the one-off charge. - `price` Price, required: Represents a price entity. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `description` string, required: Internal description for this price, not shown to customers. Typically notes for your team. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `name` string, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` Duration, required - … - `trial_period` PriceTrialDuration, required - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` Money, required: A base representation of monetary value unformatted in the lowest denomination with currency code. - … - `unit_price_overrides` UnitPriceOverride[], required: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. - … - `quantity` PriceQuantity, required - … - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `custom_data` CustomData, required: Your own structured key-value data. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - … - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `quantity` integer, required: Quantity of the item on the subscription at the time of the history entry. - `on_payment_failure` 'prevent_change' | 'apply_change', required: How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_past_due` actions. - `action` 'subscription_past_due', required: What happened on the subscription. - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required: Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_paused` actions. - `action` 'subscription_paused', required: What happened on the subscription. - `effective_from` 'immediately' | 'next_billing_period', required: When the subscription pause took effect. - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required: Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - object: Details specific to `subscription_payment_attempted` actions. Recorded when a payment attempt fails for an operation that attempts a payment, like a subscription update or one-time charge. Successful payment outcomes are captured by the relevant action, like `subscription_item_added`, `subscription_one_off_charge_applied`, or `subscription_activated`. - `action` 'subscription_payment_attempted', required: What happened on the subscription. - `operation` 'subscription_update' | 'subscription_one_off_charge' | 'subscription_activate', required: The operation that triggered the failed payment attempt. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_payment_method_added` actions. - `action` 'subscription_payment_method_added', required: What happened on the subscription. - object: Details specific to `subscription_payment_method_removed` actions. - `action` 'subscription_payment_method_removed', required: What happened on the subscription. - object: Details specific to `subscription_payment_method_updated` actions. - `action` 'subscription_payment_method_updated', required: What happened on the subscription. - object: Details specific to `subscription_renewed` actions. - `action` 'subscription_renewed', required: What happened on the subscription. - `next_billed_at` string, date-time, required: RFC 3339 datetime string. - `current_billing_period` TimePeriod, required - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`. - object: Details specific to `subscription_resumed` actions. - `action` 'subscription_resumed', required: What happened on the subscription. - `status` 'active' | 'canceled' | 'past_due' | 'paused' | 'trialing', required: Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change. - `on_resume` 'continue_existing_billing_period' | 'start_new_billing_period', required: How Paddle should set the billing period for the subscription when resuming. If omitted, defaults to `start_new_billing_period`. - object: Details specific to `subscription_scheduled_change_added` actions. - `action` 'subscription_scheduled_change_added', required: What happened on the subscription. - `scheduled_change` SubscriptionScheduledChange, required: Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. `null` if no scheduled changes. - `action` 'cancel' | 'pause' | 'resume', required: Kind of change that's scheduled to be applied to this subscription. - `effective_at` string, date-time, required: RFC 3339 datetime string. - `resume_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_scheduled_change_removed` actions. - `action` 'subscription_scheduled_change_removed', required: What happened on the subscription. - `scheduled_change` SubscriptionScheduledChange, required: Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. `null` if no scheduled changes. - `action` 'cancel' | 'pause' | 'resume', required: Kind of change that's scheduled to be applied to this subscription. - `effective_at` string, date-time, required: RFC 3339 datetime string. - `resume_at` string, date-time, required: RFC 3339 datetime string. - object: Details specific to `subscription_scheduled_change_updated` actions. - `action` 'subscription_scheduled_change_updated', required: What happened on the subscription. - `scheduled_change` SubscriptionScheduledChange, required: Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. `null` if no scheduled changes. - `action` 'cancel' | 'pause' | 'resume', required: Kind of change that's scheduled to be applied to this subscription. - `effective_at` string, date-time, required: RFC 3339 datetime string. - `resume_at` string, date-time, required: RFC 3339 datetime string. - `meta` PaginatedMeta, required: Information about this response. - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request. - `pagination` Pagination, required: Keys used for working with paginated results. - `per_page` integer, required: Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum. - `next` string, uri, required: URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`. - `has_more` boolean, required: Whether this response has another page. - `estimated_total` integer: Estimated number of entities for this response. For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated. Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-10-19** (v1) `4f35a8c6ea4d`: 13 breaking, 1 warning, 1 info - for the `query` request parameter `order_by`, default value was changed from `occurred_at[DESC]` to `id[DESC]` - added `#/components/schemas/CountryCodeNonSupported` to the `data/items/detail/allOf[#/components/schemas/SubscriptionHistoryDetail]/oneOf[subschema #12: Created]/address/anyOf[subschema #1: Address]/country_code/allOf[#/components/schemas/CountryCode]/` response property `oneOf` list for the response status `200` - added `#/components/schemas/CountryCodeNonSupported` to the `data/items/detail/allOf[#/components/schemas/SubscriptionHistoryDetail]/oneOf[subschema #12: Created]/items/anyOf[subschema #1]/items/price/allOf[subschema #1: Price]/trial_period/anyOf[subschema #1: Price Trial Duration]/unit_price_overrides/items/country_codes/items/` response property `oneOf` list for the response status `200` - added `#/components/schemas/CountryCodeNonSupported` to the `data/items/detail/allOf[#/components/schemas/SubscriptionHistoryDetail]/oneOf[subschema #12: Created]/items/anyOf[subschema #1]/items/price/allOf[subschema #1: Price]/unit_price_overrides/items/country_codes/items/` response property `oneOf` list for the response status `200` - …11 more - **2026-07-09** (v1) `e1ac347eb3c5`: 1 info - endpoint added [Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/subscriptions/:subscription_id/history/get.md) --- [API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)