Subscription cancellation

Canceling a subscription is the end of the subscription lifecycle. Billing is stopped indefinitely for canceled subscriptions, so Paddle doesn't create any transactions or collect payment for it.

You should provision so customers don't have access to your app when canceled.

In some jurisdictions, you must offer a way for customers to cancel their subscription. Paddle automatically includes a link to cancel in subscription-related emails sent to your customers.

How it works

You can build a workflow to cancel using the cancel subscription operation in the Paddle 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. Paddle doesn't automatically refund customers where subscriptions are canceled mid-cycle.

Subscription-related emails sent from Paddle to your customers include a link to cancel. When customers cancel using the link in the email from Paddle, their subscription remains active until the end of the current billing period.

How to cancel a subscription

Events

1. Scheduled change created — canceling on next billing period only

   This step only occurs when subscriptions are canceled on the next billing period. This includes when customers click the link in subscription-related emails from Paddle.

   subscription.updated	If canceled on the next billing period, Paddle updates the scheduled_change object against the subscription to say the subscription is set to cancel.

2. Subscription cancels

   subscription.updated	When scheduled_change.effective_from elapses, or if canceled immediately, Paddle updates billing dates for the subscription and any items. Its status changes to canceled.
   subscription.canceled	Occurs because the subscription status changes to canceled.

Emails

For compliance reasons, Paddle sends emails for subscription lifecycle events.

When a subscription is canceled, Paddle sends:

Recommended workflow

When you cancel a subscription immediately, Paddle doesn't automatically refund or credit customers for any unused time. Paddle charges for a full billing cycle on resume.

1. Check for unbilled charges — canceling on next billing period only

   If a subscription has one-time charges or charges for subscription changes that were set to be billed on the next billing period, these are automatically forgiven when a subscription is canceled.

    

   As part of your subscription cancel workflow, we recommend that you get a subscription including the next transaction to check for unbilled charges. You may wish to prevent a customer canceling a subscription immediately where they have unbilled charges.

2. Check for past due transactions

   If a subscription has past due transactions, these are automatically canceled when a subscription is canceled.

    

   As part of your subscription cancel workflow, you may wish to prevent a customer canceling a subscription immediately where their subscription status is past_due. You can get transactions for a subscription where the status is past_due using the list transactions operation with the subscription_id and status query parameters.

3. Listen for events

   We recommend that you listen for:

   subscription.updated	Get notified when a subscription is updated. Occurs when a scheduled change to cancel is created for a subscription, and when a scheduled change is removed.
   subscription.canceled	Get notified when a subscription is canceled. Occurs when its status changes to canceled.

4. Store information in your database

   Update the record for a subscription in your database for the cancellation based on webhooks received. As well as checking and storing the occurred_at date against notifications, you'll typically need to update:

   Description	Field name	Reason to store
   Subscription status	subscription.status	Used to limit or stop access when canceled, and determine if a subscription is past due.
   Cancellation date	subscription.canceled_at, subscription.scheduled_change.effective_at	Used to determine if a subscription is canceled. canceled_at is null until cancellation is processed.
   Scheduled change	subscription.scheduled_change	Used to determine if a subscription has a scheduled change to pause, resume, or cancel. You can't make some changes to a subscription where there are scheduled changes.
   Next billing date	subscription.next_billed_at	Used to determine when a subscription renews if active. null if a subscription is scheduled to be canceled.

   You may like to store and update other fields if you'd like to build a more complete billing and subscription management experience, see: Handle provisioning and fulfillment

5. Update your frontend — canceling on next billing period only

   You can't make changes to items on a subscription with a scheduled change. Build logic in your frontend to prevent changes to subscriptions that are scheduled to cancel.

    

   We recommend providing a way for customers to cancel their scheduled cancellation by removing the scheduled change.

6. Provision

   When a subscription is canceled, provision so that your customer no longer has access to your app.

    

   Use the subscription.status field to determine whether a subscription should have access to your app. Where status is canceled, customers should have no access to your app.

7. Build a workflow for returning customers

   While you can't reinstate a canceled subscription in Paddle, you might like to build a workflow for returning customers. When customers try to log in to an account that's canceled, you can set up a transaction with the same details that were against their previous subscription to make it easier for them to return.

8. Create an adjustment to refund customers — canceling immediately only

   Paddle doesn't automatically refund customers where subscriptions are canceled mid-cycle.

    

   You may like to create an adjustment to refund customers for any unused time on their subscription. Paddle does not calculate the amount customers should be refunded.

Related pages