Subscription pause or resume

Pausing subscriptions is an optional part of the subscription lifecycle. Billing is temporarily stopped for paused subscriptions, so Paddle doesn't create any transactions or collect payment for it. Unlike cancellation, customers can resume their subscription.

You should provision so customers don't have access to your app, or have limited access, while paused.

How it works

Pause

To offer pause functionality, build a workflow using the pause subscription operation in the Paddle API. When sending a request to pause, you can tell Paddle to:

• Pause at the end of the billing period

  Paddle creates a scheduled change to say the subscription should be paused on the next billing date. The subscription remains active until the next billing date, when the subscription status changes to paused.

• Pause immediately

  Paddle pauses the subscription right away. Its status changes to paused. Paddle doesn't automatically refund or credit customers where subscriptions are paused mid-cycle.

Pause emails from Paddle include a link to restart a subscription by sending them to a link to update their payment method.

Past due transactions for subscription renewals are automatically canceled when a subscription pauses.

Resume

Subscriptions remain paused until they're resumed. Pauses can be open-ended, or they can have a resume date.

Resume a subscription using the resume subscription operation in the Paddle API. When resuming a subscription, Paddle creates a transaction to bill for the subscription immediately. If automatically collected, Paddle collects using the payment method on file; if manually collected, Paddle creates and sends an invoice.

Subscription billing dates are recalculated based on the date the subscription resumed, and a new billing cycle starts. Paddle charges for a full billing cycle.

How to pause or resume a subscription

Events

Pause

Resume

Emails

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

Pause

When a subscription is paused, Paddle sends:

Resume

When a subscription is resumed, Paddle sends:

Recommended workflow

When you pause 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 if the subscription is past due

   If a subscription has past due transactions for renewals, these are automatically canceled when a subscription is paused. The subscription status is past_due where the latest transaction for a subscription renewal is past_due.

    

   As part of your subscription pause workflow, we recommend checking the subscription status. If past_due, you may wish to prevent a customer pausing a subscription until Paddle Retain has completed dunning. Retain can automatically pause or cancel automatically-collected subscriptions once dunning is exhausted.

2. Present customers with resume options

   You can reduce churn by offering customers a list of resume options as part of your pause workflow. For example, you can offer customers the option to pause for one, three, and six months.

    

   Send a resume_at date with a request to pause to schedule a subscription to automatically resume.

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 pause on the next billing period is created for a subscription, and when a scheduled change is removed.
   subscription.paused	Get notified when a subscription is paused. Occurs when its status changes to paused.
   subscription.resumed	Get notified when a subscription is resumed. Occurs when its status changes to active or past_due after previously being paused.

4. Update information in your database

   Update the record for a subscription in your database for the pause 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 paused, and determine if a subscription is paused or resumed.
   Pause date	subscription.paused_at, subscription.scheduled_change.effective_at	Used to determine if a subscription is paused. paused_at is null until pause 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 resumes. null if a subscription isn't scheduled to resume.

   You may like to store and update other fields if you want to build a more comprehensive billing and subscription management experience. To learn more, see Handle provisioning and fulfillment

5. Update your frontend — pausing 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 pause.

    

   We recommend providing a way for customers to cancel their scheduled pause by removing the scheduled change, letting them make changes once the scheduled change is removed.

6. Build a resume workflow

   We recommend making it as easy as possible for customers to resume their subscription, even if they have a scheduled change to automatically resume. Present customers with a preview of charge information and their next billing period, along with an option to resume immediately.

    

   Keep in mind that a customer's payment method may have expired or no longer be valid if they're resuming after a while, so you might need to present a payment details update workflow after resuming.

7. Bill for the dunning period — past due only

   Paddle automatically cancels any past due transactions when pausing a subscription. A new transaction is created on resume for the new billing period, starting the date and time that the subscription was resumed.

    

   If Paddle Retain pauses a subscription because dunning is exhausted, you may like to create a one-time charge to bill customers for the dunning period. Paddle doesn't calculate the amount you should bill for.

8. Provision

   When a subscription is paused, provision so that a customer has limited access to your app.

    

   Use the subscription.status field to determine whether a subscription should have access to your app. Where status is paused, customers should have no or limited access to your app. We recommend that you provide a way for customers to log in and resume their subscription.

    

   When a subscription is resumed, provision so that a customer has access to your app. Where subscription.status is active or past_due, customers should have full access to your app.

Related pages