Cancel a subscription

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.

Paddle supports subscriptions with multiple products. Customers might say they want to cancel when they want to remove items for an addon or users. To learn more, see Add or remove products on a subscription

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.

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

Before you begin

To cancel a subscription, you'll need to get the subscription ID for the subscription you want to cancel. You can only cancel subscriptions that are active or paused.

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

Use the subscription management URL

When working with subscriptions using the API, Paddle returns a management_urls object that includes links that you can use to update a payment method or cancel a subscription.

The simplest way to cancel a subscription is to use the get a subscription operation and return management_urls.cancel to the customer. When customers click this link, they're taken to a page hosted by Paddle that asks them to confirm that they'd like to cancel.

If confirmed, Paddle creates a scheduled change against the subscription to cancel on next renewal. Subscriptions remain active until the end of the billing period, at which point their status changes to canceled.

For security, subscription management URLs include a token parameter. This token is temporary, so you shouldn't store these URLs. The management_urls object isn't returned in events for this reason, too.

Cancel a subscription

1
2
3
1{
2  "effective_from": "next_billing_period"
3}

1
2
3
1{
2  "effective_from": "immediately"
3}

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-08T10:38:57.97967Z",
20      "ends_at": "2024-05-08T10:38:57.97967Z"
21    },
22    "billing_cycle": {
23      "frequency": 1,
24      "interval": "month"
25    },
26    "scheduled_change": {
27      "action": "cancel",
28      "effective_at": "2024-05-08T10:38:57.97967Z",
29      "resume_at": null
30    },
31    "items": [
32      {
33        "status": "active",
34        "quantity": 10,
35        "recurring": true,
36        "created_at": "2024-04-08T10:38:58.673Z",

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
4    "status": "canceled",
5    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
6    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-04-12T10:38:00.761Z",
10    "updated_at": "2024-04-12T11:24:54.873Z",
11    "started_at": "2024-04-12T10:37:59.556997Z",
12    "first_billed_at": "2024-04-12T10:37:59.556997Z",
13    "next_billed_at": null,
14    "paused_at": null,
15    "canceled_at": "2024-04-12T11:24:54.868Z",
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": null,
19    "billing_cycle": {
20      "frequency": 1,

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
2
3
1{
2  "scheduled_change": null
3}

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-08T10:38:57.97967Z",
20      "ends_at": "2024-05-08T10:38:57.97967Z"
21    },
22    "billing_cycle": {
23      "frequency": 1,
24      "interval": "month"
25    },
26    "scheduled_change": null,
27    "items": [
28      {
29        "status": "active",
30        "quantity": 10,
31        "recurring": true,
32        "created_at": "2024-04-08T10:38:58.673Z",
33        "updated_at": "2024-04-08T10:38:58.673Z",
34        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
35        "next_billed_at": "2024-05-08T10:38:57.97967Z",
36        "trial_dates": null,

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

Related pages