For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Cancel a subscription

Cancel subscriptions when a customer no longer wants to use your software. Customers must sign up again if they wish to use your software in the future.

AI summary

Cancel a subscription to permanently stop billing, set its status to canceled, and trigger provisioning logic in your app to remove customer access.

  • • When canceled at the end of the billing period, the subscription remains active until the period ends — when canceled immediately, status changes to canceled right away.
  • • Paddle includes a cancellation link in subscription emails automatically; you don't need to build this yourself, but you do need to handle the subscription.canceled webhook to revoke access.
  • • Cancellation is permanent — a canceled subscription cannot be reinstated; use pause instead if a customer wants a temporary break.

Cancel subscriptions to stop billing for them permanently. Paddle stops billing customers indefinitely.

You should restrict access to your app when a customer has canceled their subscription.

If a customer just wants to stop using your software temporarily, pause a subscription instead.

How it works

When you cancel a subscription, its status is set to canceled. Paddle stops billing for it, meaning no further transactions are created for the subscription. You should provision your app so customers don't have access when canceled.

For compliance reasons, subscription-related emails sent from Paddle to customers include a link to cancel. This is handled by Paddle — you don't need to build your own logic for this. When customers cancel using the link in the email from Paddle, their subscription remains active until the end of the current billing period.

You can also cancel a subscription using the API. When sending a request to cancel, you can tell Paddle to:

  • Cancel at the end of the billing period
    Paddle creates a scheduled change to say the subscription should be canceled on the next billing date. The subscription remains active until the next billing date, when the subscription status changes to canceled.
  • Cancel immediately
    Paddle cancels the subscription right away. Its status changes to canceled.

If you've made changes to a subscription or billed for one-time charges and set them to be charged on the next billing period, these are automatically forgiven.

Before you begin

To cancel a subscription, you'll need to get the subscription ID for the subscription you want to change.

You can use the status query parameter when listing with the value active,paused to get a list of active and paused subscriptions.

Use the portal Recommended

The quickest way to let customers cancel a subscription is to link them to the customer portal. The portal is hosted by Paddle and includes a cancellation flow out of the box, so you don't need to build your own UI.

When customers cancel using the portal, Paddle creates a scheduled change against the subscription to cancel at the end of the current billing period. The subscription remains active until the next billing date, at which point its status changes to canceled.

You can link customers to the portal in two ways:

  • Customer portal session
    Generates an authenticated, deep link straight to the cancellation page for a specific subscription. Customers don't need to sign in to the portal.
  • Subscription management URL
    A pre-generated link returned on the subscription entity. Quickest to integrate, but customers will need to sign in to the portal using their email address.

With a customer portal session

Generate a customer portal session for the customer and pass the subscription_ids of the subscriptions you want to create deep links for. Paddle returns an authenticated cancel_subscription link for each subscription that you can present in your app.

Use a customer portal session when customers are already signed in to your app, so they don't have to sign in to the portal again.

POST /customers/{customer_id}/portal-sessions
Request
{
  "subscription_ids": [
    "sub_01jcgfqad406rsfjcgq44g9djq",
    "sub_01jcdafvpe5hm4vczfefsbwhvp"
  ]
}
Response (201 Created)
{
  "data": {
    "id": "cpls_01jcggxbs9b4tff8zy7kfwwr1s",
    "customer_id": "ctm_01jcdaf4zgm2fxw3nc0e4fn137",
    "urls": {
      "general": {
        "overview": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=overview&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
      },
      "subscriptions": [
        {
          "id": "sub_01jcgfqad406rsfjcgq44g9djq",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=cancel_subscription&subscription_id=sub_01jcgfqad406rsfjcgq44g9djq&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=update_subscription_payment_method&subscription_id=sub_01jcgfqad406rsfjcgq44g9djq&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
        },
        {
          "id": "sub_01jcdafvpe5hm4vczfefsbwhvp",
          "cancel_subscription": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=cancel_subscription&subscription_id=sub_01jcdafvpe5hm4vczfefsbwhvp&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw",
          "update_subscription_payment_method": "https://customer-portal.paddle.com/cpl_01gsx07ferwf96qnjz1mrc6h0q?action=update_subscription_payment_method&subscription_id=sub_01jcdafvpe5hm4vczfefsbwhvp&token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWpjZ2d4YnNmNTEzcGY1MjZyNjZrbTMxOSIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6ImN1c3RvbWVyLXBvcnRhbC1zZXNzaW9uIiwic2NvcGUiOiJjdXN0b21lci5jaGVja291dC5jcmVhdGUgY3VzdG9tZXIuY2hlY2tvdXQucmVhZCBjdXN0b21lci5jdXN0b21lci5yZWFkIGN1c3RvbWVyLmN1c3RvbWVyLnVwZGF0ZSBjdXN0b21lci5jdXN0b21lci1hZGRyZXNzLnJlYWQgY3VzdG9tZXIuY3VzdG9tZXItcGF5bWVudC1tZXRob2QucmVhZCBjdXN0b21lci5jdXN0b21lci1wYXltZW50LW1ldGhvZC5kZWxldGUgY3VzdG9tZXIuaW52b2ljZS5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1jYW5jZWwuY3JlYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi1wYXltZW50LnJlYWQgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQudXBkYXRlIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi5yZWFkIGN1c3RvbWVyLnN1YnNjcmlwdGlvbi51cGRhdGUgY3VzdG9tZXIudHJhbnNhY3Rpb24ucmVhZCBjdXN0b21lci50cmFuc2FjdGlvbi5vcmlnaW4ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFqY2RhZjR6Z20yZnh3M25jMGU0Zm4xMzciLCJleHAiOjE3MzE1MTI4MzAsImlhdCI6MTczMTQyNjQzMH0.DHHFoLwIDWCt9F9hZmGTG3G-uhi9tUltTbMSY6Nf-vVplemJYrcC_PyF97Wm88bmHEO1f8LL3agMYNFDwvzADw"
        }
      ]
    },
    "created_at": "2024-11-12T15:47:10.761048551Z"
  },
  "meta": {
    "request_id": "0936d329-68b4-4c9f-b33c-d872d3ffbaf1"
  }
}

For more information, see Use customer portal links in your app.

With a subscription management URL

Send a GET request to the /subscriptions/{subscription_id} endpoint to get the subscription, then return management_urls.cancel to the customer.

When customers click this link, they're taken to the customer portal where they can sign in with their email address and confirm the cancellation.

GET /subscriptions/{subscription_id}

Cancel a subscription

  1. Go to Paddle > Customers, and find the customer whose subscription you want to cancel.
  2. Find the subscription under the Subscriptions heading and click it.
  3. From the subscription overview page, choose Cancel subscription
  4. Review, then choose Cancel subscription to confirm.

Send a POST request to the /subscriptions/{subscription_id}/cancel endpoint to cancel a subscription.

In your request, include effective_from to tell Paddle when to cancel the subscription — next_billing_period (default) or immediately. You can also send an empty request body to cancel on the next billing period.

Paddle creates a scheduled change with an effective_at date matching the subscription's next_billed_at date. next_billed_at is set to null.

POST /subscriptions/{subscription_id}/cancel
Request
{
  "effective_from": "next_billing_period"
}
Response (200 OK)
{
  "data": {
    "id": "sub_01htymmb3hj0q9fmckjbtrmd73",
    "status": "active",
    "customer_id": "ctm_01htymkpj07kjy7p5q1vzqpk70",
    "address_id": "add_01htymkpjq97zpchxzdyyas99v",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-08T10:38:58.673Z",
    "updated_at": "2024-04-08T10:39:28.895Z",
    "started_at": "2024-04-08T10:38:57.97967Z",
    "first_billed_at": "2024-04-08T10:38:57.97967Z",
    "next_billed_at": null,
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-08T10:38:57.97967Z",
      "ends_at": "2024-05-08T10:38:57.97967Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": {
      "action": "cancel",
      "effective_at": "2024-05-08T10:38:57.97967Z",
      "resume_at": null
    },
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2024-04-08T10:38:58.673Z",
        "updated_at": "2024-04-08T10:38:58.673Z",
        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": {
            "features": {
              "crm": true,
              "data_retention": false,
              "reports": true
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting."
          },
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-05T14:30:28.146783Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-08T10:38:58.673Z",
        "updated_at": "2024-04-08T10:38:58.673Z",
        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-05T14:33:48.860572Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01htymmb3hj0q9fmckjbtrmd73/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01htymmb3hj0q9fmckjbtrmd73/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "e52466c8-dfd7-4323-aa32-3f10912f505a"
  }
}

The subscription status changes to canceled right away.

POST /subscriptions/{subscription_id}/cancel
Request
{
  "data": {
    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
    "status": "canceled",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T10:38:00.761Z",
    "updated_at": "2024-04-12T11:24:54.873Z",
    "started_at": "2024-04-12T10:37:59.556997Z",
    "first_billed_at": "2024-04-12T10:37:59.556997Z",
    "next_billed_at": null,
    "paused_at": null,
    "canceled_at": "2024-04-12T11:24:54.868Z",
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": null,
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 20,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:49:38.76Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "product": {
          "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "name": "AeroEdit Pro",
          "type": "standard",
          "tax_category": "standard",
          "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": true,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:46.605Z",
          "updated_at": "2024-04-05T15:53:44.687Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:38:00.761Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-09T07:23:00.907834Z"
        },
        "product": {
          "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "name": "Analytics addon",
          "type": "standard",
          "tax_category": "standard",
          "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-06-01T13:30:50.302Z",
          "updated_at": "2024-04-05T15:47:17.163Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:49:38.765Z",
        "updated_at": "2024-04-12T10:49:38.765Z",
        "previously_billed_at": "2024-04-12T10:49:38.765Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "standard",
          "description": "Monthly (recurring addon)",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "25000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:59:52.159927Z",
          "updated_at": "2024-04-09T07:27:48.018296Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "VIP support",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T13:58:17.615Z",
          "updated_at": "2024-04-05T15:44:02.893Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "f21058d1-281a-4877-bb3b-261a753d08c4"
  }
}
Response (200 OK)
{
  "data": {
    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
    "status": "canceled",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T10:38:00.761Z",
    "updated_at": "2024-04-12T11:24:54.873Z",
    "started_at": "2024-04-12T10:37:59.556997Z",
    "first_billed_at": "2024-04-12T10:37:59.556997Z",
    "next_billed_at": null,
    "paused_at": null,
    "canceled_at": "2024-04-12T11:24:54.868Z",
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": null,
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 20,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:49:38.76Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "product": {
          "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "name": "AeroEdit Pro",
          "type": "standard",
          "tax_category": "standard",
          "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": true,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:46.605Z",
          "updated_at": "2024-04-05T15:53:44.687Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:38:00.761Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-09T07:23:00.907834Z"
        },
        "product": {
          "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "name": "Analytics addon",
          "type": "standard",
          "tax_category": "standard",
          "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-06-01T13:30:50.302Z",
          "updated_at": "2024-04-05T15:47:17.163Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:49:38.765Z",
        "updated_at": "2024-04-12T10:49:38.765Z",
        "previously_billed_at": "2024-04-12T10:49:38.765Z",
        "next_billed_at": null,
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "standard",
          "description": "Monthly (recurring addon)",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "25000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:59:52.159927Z",
          "updated_at": "2024-04-09T07:27:48.018296Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "VIP support",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T13:58:17.615Z",
          "updated_at": "2024-04-05T15:44:02.893Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "f21058d1-281a-4877-bb3b-261a753d08c4"
  }
}

Remove a scheduled change

You can stop a cancellation from going through at the end of the billing period by removing the scheduled change.

  1. Go to Paddle > Customers, and find the customer whose subscription you want to remove a scheduled cancel against.
  2. Find the subscription under the Subscriptions heading and click it.
  3. From the subscription overview page, choose Don't cancel

Send a PATCH request to the /subscriptions/{subscription_id} endpoint to update the subscription.

In your request, set scheduled_change to null to remove the scheduled cancellation.

PATCH /subscriptions/{subscription_id}
Request
{
  "scheduled_change": null
}
Response (200 OK)
{
  "data": {
    "id": "sub_01htymmb3hj0q9fmckjbtrmd73",
    "status": "active",
    "customer_id": "ctm_01htymkpj07kjy7p5q1vzqpk70",
    "address_id": "add_01htymkpjq97zpchxzdyyas99v",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-08T10:38:58.673Z",
    "updated_at": "2024-04-08T10:44:18.005Z",
    "started_at": "2024-04-08T10:38:57.97967Z",
    "first_billed_at": "2024-04-08T10:38:57.97967Z",
    "next_billed_at": "2024-05-08T10:38:57.97967Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-08T10:38:57.97967Z",
      "ends_at": "2024-05-08T10:38:57.97967Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2024-04-08T10:38:58.673Z",
        "updated_at": "2024-04-08T10:38:58.673Z",
        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
        "next_billed_at": "2024-05-08T10:38:57.97967Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": {
            "features": {
              "crm": true,
              "data_retention": false,
              "reports": true
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting."
          },
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-05T14:30:28.146783Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-08T10:38:58.673Z",
        "updated_at": "2024-04-08T10:38:58.673Z",
        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
        "next_billed_at": "2024-05-08T10:38:57.97967Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon) ",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-05T14:33:48.860572Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01htymmb3hj0q9fmckjbtrmd73/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01htymmb3hj0q9fmckjbtrmd73/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "a37dc0cb-0337-45cb-8f2c-8bd31db37553"
  }
}

Reinstate a cancelled subscription

Canceled subscriptions can't be reinstated. Create a new subscription for customers who have canceled if they want to return.

To streamline this process, create a transaction with the same items and other information as on the previous subscription:

  1. Get the previous subscription
    List subscriptions using the customer_id query parameter, passing the Paddle ID for the customer as the value. This returns a list of all subscriptions for this customer. Get the subscription that they previously canceled.
  2. Extract price IDs and quantities
    Extract the price ID from the price object and the quantity for each item in the items array against the canceled subscription entity. You may also like to extract the currency_code, address_id, and business_id if they're going to be the same.
  3. Build a request to create a transaction
    Build a request with an items array with an object for each price that contains a price ID and a quantity, along with the customer ID and any other information you extracted from the canceled subscription.
  4. Create a transaction
    Send a POST request to the /transactions endpoint to create a transaction. Paddle returns a new transaction for the customer, items, and other details you passed.
  5. Pass to Paddle Checkout
    Collect payment and create a new subscription by getting the checkout.url against the created transaction and returning it to the customer, or pass a transaction ID to Paddle.js to open a checkout for the transaction you created.

Events

For a full list of events that occur when a subscription is canceled, see Subscription cancellation

Was this page helpful?