---
title: "Cancel a subscription"
method: POST
path: "/subscriptions/{subscription_id}/cancel"
tags: ["Subscriptions"]
---

# Cancel a subscription

`POST /subscriptions/{subscription_id}/cancel`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/subscriptions/{subscription_id}/cancel`
- Auth: HTTP bearer

Cancels a subscription using its ID.

By default, active subscriptions are canceled at the end of the billing period. When you send a request to cancel, Paddle creates a `scheduled_change` against the subscription entity to say that it should cancel at the end of the current billing period. Its `status` remains `active` until after the effective date of the scheduled change, at which point it changes to `canceled`.

You can cancel a subscription right away by including `effective_from` in your request, setting the value to `immediately`. If successful, your response includes a copy of the updated subscription entity with the `status` of `canceled`. Paused subscriptions can only be canceled immediately, so you must set `effective_from` to `immediately` to cancel them.

You can cancel subscriptions that are `past_due`. If you cancel at the end of the billing period, the `status` remains `past_due` until the end of the current billing period. Cancel immediately to stop the subscription right away.

You can't reinstate a canceled subscription.

## Path parameters

- `subscription_id` string, required

## Request body

- SubscriptionCancel
  - `effective_from` 'next_billing_period' | 'immediately': When this subscription change should take effect from. Defaults to `next_billing_period`, which creates a `scheduled_change` to apply the subscription change at the end of the billing period.

## Response `200`

The request has succeeded.

- object
  - `data` Subscription, required: Represents a subscription 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, 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 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.
    - `started_at` string, date-time, required: RFC 3339 datetime string.
    - `first_billed_at` string, date-time, required: RFC 3339 datetime string.
    - `next_billed_at` string, date-time, required: RFC 3339 datetime string.
    - `paused_at` string, date-time, required: RFC 3339 datetime string.
    - `canceled_at` string, date-time, required: RFC 3339 datetime string.
    - `discount` SubscriptionDiscount, 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, required: RFC 3339 datetime string.
      - `ends_at` string, date-time, required: RFC 3339 datetime string.
      - `type` 'recurring' | 'one-off', required: Whether this discount applies for multiple billing periods.
    - `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.
    - `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.
    - `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.
    - `management_urls` SubscriptionManagementUrls, required: Customer portal deep links for this subscription. Authenticated links are only returned when your API key has Customer portal session (Write) permission. For security, the `token` appended to authenticated links is temporary. You shouldn't store them.
      - `update_payment_method` string, uri, nullable, required: Link to the page for this subscription in the customer portal with the payment method update form pre-opened. Use as part of workflows to let customers update their payment details. `null` for manually-collected subscriptions.
      - `cancel` string, uri, required: Link to the page for this subscription in the customer portal with the subscription cancellation form pre-opened. Use as part of cancel subscription workflows.
      - `view_subscription` string, uri, required: Link to the page for this subscription in the customer portal, with no form pre-opened. Use to let customers manage the subscription themselves rather than sending them into one specific action.
    - `items` ItemSubscription[], required: List of items on this subscription. Only recurring items are returned.
      - `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 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.
      - `previously_billed_at` string, date-time, required: RFC 3339 datetime string.
      - `next_billed_at` string, date-time, required: RFC 3339 datetime string.
      - `trial_dates` TimePeriod, required
        - `starts_at` string, date-time, required: RFC 3339 datetime string.
        - `ends_at` string, date-time, required: RFC 3339 datetime string.
      - `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.
            - `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` 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.
            - `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` MoneyOptionalCurrency, required: A representation of monetary value unformatted in the lowest denomination with optional currency code.
              - …
        - `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.
            - union
              - …
          - `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.
        - `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.
      - `product` Product, required: Represents a product entity.
        - `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` CustomData, 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: 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.
    - `custom_data` CustomData, required: Your own structured key-value data.
    - `import_meta` object, nullable, required: Import information for the subscription 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.
    - `consent_requirements` SubscriptionConsentRequirement[], 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` 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.
  - `meta` Meta, 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.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-10-19** (v1) `4f35a8c6ea4d`: 2 breaking, 1 info
  - added `#/components/schemas/CountryCodeNonSupported` to the `data/items/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/items/price/allOf[subschema #1: Price]/unit_price_overrides/items/country_codes/items/` response property `oneOf` list for the response status `200`
  - added the required property `data/management_urls/allOf[subschema #1: Subscription Management Urls]/view_subscription` to the response with the `200` status
- **2026-07-09** (v1) `e1ac347eb3c5`: 6 warning, 5 info
  - added the new `CLP` enum value to the `data/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `200`
  - added the new `CLP` enum value to the `data/items/items/price/allOf[subschema #1: Price]/unit_price/allOf[subschema #1: Money]/currency_code` response property for the response status `200`
  - added the new `CLP` enum value to the `data/items/items/price/allOf[subschema #1: Price]/unit_price_overrides/items/unit_price/allOf[subschema #1: Money]/currency_code` response property for the response status `200`
  - added the new `PEN` enum value to the `data/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `200`
  - …7 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/subscriptions/:subscription_id/cancel/post.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)