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.

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

Resume

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

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

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

   subscription.updated	If 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.updated	When 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.paused	Occurs because the subscription status changes to paused.

Resume

1. Subscription resumes

   subscription.updated	The subscription and its items are updated with new billing dates. If there was a scheduled change to resume, this is set to null.
   subscription.resumed	Occurs because the subscription resumed.
   transaction.created	Paddle 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.billed	Occurs because the transaction status changes to billed.

2. Payment collected successfully

   transaction.updated	The transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
   transaction.paid	Occurs because the transaction status changes to paid.
   transaction.updated	An invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
   transaction.completed	Occurs 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:

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 for unbilled charges

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

    

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

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 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 valid if they're resuming after a while, so you might need to present a payment details update workflow after resuming.

7. Provision

   When a subscription is paused, provision so that your 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 your customer has access to your app. Where subscription.status is active or past_due, customers should have full access to your app.

Related pages