Paddle Billing
Search

Subscription cancellation

Cancel subscriptions when a customer no longer wants to use your software.

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 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 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

This guide is overview of events that typically occur. Depending on the customer journey and how you build your workflows, not all events listed may occur, or additional events may occur.

We can't guarantee the order of delivery for webhooks. Store and check the occurred_at date against a webhook before making changes.

  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.updatedIf 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.updatedWhen 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.canceledOccurs 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:

Screenshot showing a scheduled cancellation email. It includes a list of items, total, and the billing period. There is a paragraph that says: 'you have access to your subscription until the end of your billing cycle', followed by a date.

Cancellation scheduled

Your subscription for [company] will be canceled

Lets the customer know that their subscription is scheduled to be canceled and when the cancellation is effective from. Includes a list of items on the subscription, along with totals and billing periods.

Screenshot showing a cancellation email. It includes a list of items, total, and the billing period. There is a paragraph that says: 'you have access to your subscription until the end of your billing cycle', followed by a date.

Subscription canceled

Your subscription for [company] has been canceled

Lets the customer know that the subscription is now canceled. Includes a list of items on the subscription, along with totals and billing periods.

Screenshot showing a scheduled change removal email. There is a heading that says 'Thanks for sticking around!', followed by the next subscription renewal date. It includes a list of items, total, and the billing period.

Scheduled cancellation removed

Your subscription for [company] will remain active

Tells the customer that their subscription is now going to renew as normal, and the date of their next renewal. Includes a list of items on the subscription, along with totals and billing periods.

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.updatedGet 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.canceledGet 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:

    DescriptionField nameReason to store
    Subscription statussubscription.statusUsed to limit or stop access when canceled, and determine if a subscription is past due.
    Cancellation datesubscription.canceled_at, subscription.scheduled_change.effective_atUsed to determine if a subscription is canceled. canceled_at is null until cancellation is processed.
    Scheduled changesubscription.scheduled_changeUsed 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 datesubscription.next_billed_atUsed 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 customers no longer have 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