--- title: "subscription.paused" method: POST path: "subscription.paused" tags: ["Subscriptions"] --- # subscription.paused `POST subscription.paused` (webhook) Occurs when a subscription is paused. Its `status` field changes to `paused`. If you choose to pause a subscription immediately, the subscription status changes to `paused` and `subscription.paused` occurs. If you choose to pause a subscription on the next billing period, Paddle creates a scheduled change to say the subscription should be paused on the next billing date. [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) occurs at this point. On the next billing date, the subscription status changes to `paused` and `subscription.paused` occurs. Payload includes the complete subscription entity, except `management_urls`. Subscription management links are temporary, so they're not included. [Get a subscription using the API](https://developer.paddle.com/api-reference/subscriptions/get-subscription) to get management links for a subscription. ## Headers - `paddle_signature` string, required ## Payload - object - `event_id` string, required: Unique Paddle ID for this event, prefixed with `evt_`. - `event_type` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`. - `occurred_at` string, date-time, required: RFC 3339 datetime string of when this event occurred. - `notification_id` string, required: Unique Paddle ID for this notification, prefixed with `ntf_`. - `data` object, required: New or changed entity. - `id` string, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`. - `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. - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`. - `address_id` string, required: Unique Paddle ID for this address entity, prefixed with `add_`. - `business_id` string, nullable, required: Unique Paddle ID for this business entity, prefixed with `biz_`. - `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. - `created_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string. - `started_at` string, date-time, nullable, required: RFC 3339 datetime string. - `first_billed_at` string, date-time, nullable, required: RFC 3339 datetime string. - `next_billed_at` string, date-time, nullable, required: RFC 3339 datetime string. - `paused_at` string, date-time, nullable, required: RFC 3339 datetime string. - `canceled_at` string, date-time, nullable, required: RFC 3339 datetime string. - `discount` object, nullable, required: Details of the discount applied to this subscription. - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`. - `starts_at` string, date-time, nullable, required: RFC 3339 datetime string. - `ends_at` string, date-time, nullable, required: RFC 3339 datetime string. - `type` 'recurring' | 'one-off', required: Whether this discount applies for multiple billing periods. - `collection_mode` 'automatic' | 'manual', nullable, required: How payment is collected. `automatic` for checkout, `manual` for invoices. - `billing_details` object, nullable, 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` object, required: How long a customer has to pay this invoice once issued. The invoice is due at the end of its payment terms, and is marked as `past_due` 24 hours after its due date if unpaid. - `interval` 'day' | 'week' | 'month' | 'year', required: Unit of time. - `frequency` integer, required: Amount of time. - `current_billing_period` object, nullable, required: Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. `null` for `paused` and `canceled` subscriptions. - `starts_at` string, date-time, required: RFC 3339 datetime string of when this period starts. - `ends_at` string, date-time, required: RFC 3339 datetime string of when this period ends. - `billing_cycle` object, required: How often this subscription renews. Set automatically by Paddle based on the prices on this subscription. - `interval` 'day' | 'week' | 'month' | 'year', required: Unit of time. - `frequency` integer, required: Amount of time. - `scheduled_change` object, nullable, 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 of when this scheduled change takes effect. - `resume_at` string, date-time, nullable, required: RFC 3339 datetime string. - `items` object[], required - `status` 'active' | 'inactive' | 'trialing', required: Status of this subscription item. Set automatically by Paddle. - `quantity` number, required: Quantity of this item on the subscription. - `recurring` boolean, required: Whether this is a recurring item. `false` if one-time. - `created_at` string, date-time, required: RFC 3339 datetime string of when this item was added to this subscription. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this item was last updated on this subscription. - `previously_billed_at` string, date-time, nullable, required: RFC 3339 datetime string. - `next_billed_at` string, date-time, nullable, required: RFC 3339 datetime string. - `trial_dates` object, nullable, required: Trial dates for this item. - `starts_at` string, date-time, required: RFC 3339 datetime string of when this period starts. - `ends_at` string, date-time, required: RFC 3339 datetime string of when this period ends. - `price` object, required: Related price entity for this item. This reflects the price entity at the time it was added to the subscription. - `id` string, required: Unique Paddle ID for this price, prefixed with `pri_`. - `product_id` string, required: Paddle ID for the product that this price is for, 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, nullable, required: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. - `billing_cycle` object, nullable, required: How often this price should be charged. `null` if price is non-recurring (one-time). - `interval` 'day' | 'week' | 'month' | 'year', required: Unit of time. - `frequency` integer, required: Amount of time. - `trial_period` object, nullable, required: Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billing_cycle`. - `interval` 'day' | 'week' | 'month' | 'year', required: Unit of time. - `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` object, nullable: A representation of monetary value unformatted in the lowest denomination with optional 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': Supported three-letter ISO 4217 currency code. - `unit_price_overrides` object[]: 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. - `country_codes` union[], required: Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price. - … - `unit_price` object, required: Override price. This price applies to customers located in the countries for this unit price override. - … - `tax_mode` 'account_setting' | 'external' | 'internal' | 'location', required: How tax is calculated for this price. - `unit_price` object, required: Base price. This price applies to all customers, except for customers located in countries where you have `unit_price_overrides`. - `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` object[], 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` union[], required: Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price. - union - … - `unit_price` object, required: Override price. This price applies to customers located in the countries for this unit price override. - `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. - `quantity` object, required: Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. - `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` object, nullable, 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, nullable: 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. - `product` object, required: Related product entity for this item. This reflects the product entity at the time it was added to the subscription. - `id` string, required: Unique Paddle ID for this product, prefixed with `pro_`. - `name` string, required: Name of this product. - `description` string, nullable, required: Short description for this product. - `type` 'custom' | 'standard', required: Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. - `tax_category` 'digital-goods' | 'ebooks' | 'implementation-services' | 'professional-services' | 'saas' | 'software-programming-services' | 'standard' | 'training-services' | 'website-hosting', required: Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account. - `image_url` union, required: Image for this product. Included in the checkout and on some customer documents. - string, uri: A URL to an image. - string - `custom_data` object, nullable, required: Your own structured key-value data. - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle. - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported. - `external_id` string, nullable: 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. - `consent_requirements` object[], nullable, required: List of active consent requirements for the subscription's current billing period. - `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` object, nullable, required: Period during which consent for this subscription can be granted. `null` if there is no `next_billed_at` or the consent requirement does not apply to the current billing period. - `starts_at` string, date-time, required: RFC 3339 datetime string of when this period starts. - `ends_at` string, date-time, required: RFC 3339 datetime string of when this period ends. - `granted_at` string, date-time, nullable, required: RFC 3339 datetime string. - `voided_at` string, date-time, nullable, required: RFC 3339 datetime string. - `custom_data` object, nullable, 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, nullable: 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. ## Acknowledgement `200` Respond with an HTTP 200 status code within 5 seconds to let Paddle know that you successfully received the message. If your server sends another kind of status code or doesn't respond, Paddle automatically retries using an exponential backoff schedule. --- [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)