Paddle Billing
Search

Subscription pause or resume

Pause subscriptions when customers want to take a break and come back later.

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

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.

Pause

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

    This step only occurs when subscriptions are paused on the next billing period.

    subscription.updatedIf paused on the next billing period, Paddle updates the scheduled_change object against the subscription to say the subscription is set to pause.
  2. Subscription pauses

    subscription.updatedWhen scheduled_change.effective_from elapses, or if paused immediately, Paddle updates billing dates for the subscription and any items. Its status changes to paused.
    subscription.pausedOccurs because the subscription status changes to paused.
  3. Past due renewal transactions canceled — past due only

    This step only occurs when subscriptions have past due transactions for renewals.

    transaction.updatedWhen a subscription has transactions with the origin of subscription_recurring and the status of past_due, Paddle automatically cancels them to avoid double-charging a customer on resume when a new billing period is created. The related transaction status is changed to canceled.
    transaction.canceledOccurs because the related transaction status changes to canceled.

Resume

  1. Subscription resumes

    subscription.updatedThe subscription and its items are updated with new billing dates. If there was a scheduled change to resume, this is set to null.
    subscription.resumedOccurs because the subscription resumed.
    transaction.createdPaddle creates a transaction for recurring items on the subscription. Its status is billed, meaning no changes can be made to the transaction. Its origin is subscription_updated.
    transaction.billedOccurs because the transaction status changes to billed.
  2. Payment collected successfully

    transaction.updatedThe transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
    transaction.paidOccurs because the transaction status changes to paid.
    transaction.updatedAn invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
    transaction.completedOccurs because the transaction status changes to completed.

    If collection is unsuccessful, a subscription becomes past due and dunning starts.

Emails

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

Pause

When a subscription is paused, Paddle sends:

Screenshot showing a scheduled pause 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.

Pause scheduled

Your subscription for [company] will be paused

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

Screenshot showing a pause 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. There is a blue button that says 'Restart subscription'.

Subscription paused

Your subscription for [company] has been paused

Lets the customer know that the subscription is now paused. There is a button that they can use to resume a subscription. 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 pause 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.

Resume

When a subscription is resumed, Paddle sends:

Screenshot showing a resume email. There is some text that says 'Thanks for choosing [company]. Find the details of your subscription below'. It includes a list of items, total, and the billing period.

Subscription resumed

Your subscription for [company] has been resumed

Lets a customer know that their subscription has been resumed. Includes a list of items on the subscription, along with totals and billing periods.

Screenshot showing a receipt email. It includes a list of items, total, and billing date.

Receipt

Your receipt from [company]

List of items purchased, along with totals and purchase date. Includes a PDF invoice for their records.

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.updatedGet 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.pausedGet notified when a subscription is paused. Occurs when its status changes to paused.
    subscription.resumedGet 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:

    DescriptionField nameReason to store
    Subscription statussubscription.statusUsed to limit or stop access when paused, and determine if a subscription is paused or resumed.
    Pause datesubscription.paused_at, subscription.scheduled_change.effective_atUsed to determine if a subscription is paused. paused_at is null until pause 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 resumes. null if a subscription is not scheduled to resume.

    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 — 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 does not 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