Paddle Billing
Search

Pause a subscription

Pause subscriptions when customers want to take a break and come back later. Offering the option to pause a subscription can lower voluntary churn and increase customer LTV.

Pause subscriptions to stop billing for them temporarily. Paddle doesn't bill for paused subscriptions until they're resumed.

You may wish to give your customers some level of access to your software while paused to maintain a relationship and encourage them to return. For example, you might let customers download reports or access existing data, but restrict their access to create records.

If a customer doesn't want to use your software at all, cancel instead. You can't reinstate a canceled subscription.

How it works

When you pause a subscription, its status is set to paused and Paddle doesn't create any transactions or collect payment for it. You should provision access to your app so customers don't have access, or have limited access, while paused.

Subscriptions remain paused until they're resumed. Pauses can be open-ended, or you can set a resume date. We recommend giving customers a set of pause duration options in your frontend — for example, 30 days, 60 days, or 90 days.

You can resume a paused subscription at any time, even if there's a resume date already set, by sending a request to resume. It's good practice to make it as easy as possible for customers to resume their subscription, so we recommend building a way for self-serve customers to reactivate their account.

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.

If you've made changes to a subscription or billed for one-time charges and told Paddle to charge on the next billing period, these are automatically forgiven.

Before you begin

You can't make changes to a subscription if the next billing period is within 30 minutes.

To pause a subscription, you'll need to get the subscription ID for the subscription you'd like to pause. You can only pause subscriptions that are active.

You can use the status query parameter with the value active when listing subscriptions to get active subscriptions.

Pause a subscription

Pause a subscription using the API to build your own pause workflow into your app.

Pause in two steps:

  1. Build a request

    Build a request that includes effective_from and resume_at to tell Paddle when you'd like a subscription to pause and resume.

  2. Pause subscription

    Send the request to pause your subscription. Paddle pauses your subscription now or in the future.

Build request

Build a request that includes effective_from to tell Paddle when you'd like a subscription to pause.

You don't need to do this if you're pausing on the next billing period with no resume date. You can send an empty request.

effective_fromstring

When this subscription change should take effect from. Defaults to next_billing_period, which creates a scheduled_change to apply the subscription change at the end of the billing period.

To set a date when a subscription should resume, include resume_at in your request. We recommend giving customers a set of pause duration options in your frontend.

Omit to create an open-ended pause. Subscriptions are paused indefinitely until they're explicitly resumed.

resume_atstring<date-time> or null

RFC 3339 datetime string of when the paused subscription should resume. Omit to pause indefinitely until resumed.

Pause subscription

Send a POST request to the /subscriptions/{subscription_id}/pause endpoint with the request you built.

POSThttps://api.paddle.com/subscriptions/{subscription_id}/pause
subscription_idstring

Paddle ID of the subscription entity to work with.

Remove a scheduled change

You can stop a pause from going through at the end of the billing period by removing the scheduled change.

You might also do this to remove a scheduled resume from a paused subscription, so it's paused indefinitely until you resume.

Remove a scheduled pause using the API in two steps:

  1. Build a request

    Build a request that removes the scheduled change.

  2. Remove scheduled change

    Send the request to remove the scheduled change. If active, a subscription is no longer scheduled to pause. If paused, a subscription is no longer scheduled to resume.

Build request

Remove a scheduled pause using the API by sending a request that sets scheduled_change to null.

scheduled_changenull

Change that's scheduled to be applied to a subscription. null if no scheduled changes.

Request

Remove scheduled change

Send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.

Response

If successful, Paddle responds with the updated subscription entity. Scheduled change is set to null and the status is active.

Set or change a resume date

You can change when a paused subscription is set to resume, or set a resume date where a subscription is paused indefinitely.

To change the future resume date for an active subscription that's scheduled to pause, remove the scheduled change then send a request to pause with a resume date.

Set or change the resume date for a paused subscription using the API in two steps:

  1. Build a request

    Build a request that includes the new resume date.

  2. Set or change the resume date

    Send the request to change the resume date. Paddle updates the scheduled change to include the new or changed resume date.

Build request

Set or change the resume date for a subscription by building a request that includes effective_from.

Pass either:

  • An RFC 3339 timestamp to resume a subscription on a specific date and time.
  • next_billing_period to resume a subscription on the next billing period.
effective_fromstring or null

When this subscription change should take effect from. Defaults to next_billing_period for active subscriptions, which creates a scheduled_change to apply the subscription change at the end of the billing period.

Request

Set or change resume date

Send a POST request to the /subscriptions/{subscription_id}/resume endpoint with the request that you built.

POSThttps://api.paddle.com/subscriptions/{subscription_id}/resume
subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a copy of the subscription entity with a scheduled change set to resume_at the date in your request.

The resume_at date is the new next_billed_at date for the subscription.

Resume a paused subscription

Resume a subscription to start billing for it again. You should grant your customer access to your app once resumed.

When resumed, Paddle bills for the subscription immediately. The subscription billing date is recalculated based on the resume date.

To resume on a particular date, see: Set or change a resume date (above)

Resume a paused subscription using the API in two steps:

  1. Preview resumed subscription

    Preview charging for the subscription. This is optional, but recommended — you should present charge information to your customer if you let your customer resume a subscription in your frontend.

  2. Resume subscription

    Send a request to resume the subscription. Paddle updates the subscription and starts charging for it.

Preview charging

Send a GET request to the /subscriptions/{subscription_id} endpoint, using the include query parameter with the value recurring_transaction_details.

Response

If successful, Paddle returns the paused subscription entity with an object that that contains a preview of the recurring transaction for this subscription.

Resume subscription

Send a POST request to the /subscriptions/{subscription_id}/resume endpoint. Send an empty request body.

POSThttps://api.paddle.com/subscriptions/{subscription_id}/resume
subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a copy of the updated subscription entity. The subscription status is active, and billing dates are updated to reflect the resume date.

Notifications

subscription.updatedOccurs when Paddle creates a scheduled change to pause, when you remove a scheduled change, and if you make changes to a resume date.
subscription.pausedOccurs when a subscription status changes to paused because a subscription is set to pause immediately, or because a scheduled change is processed.
subscription.resumedOccurs when a subscription is resumed.
transaction.createdOccurs when a subscription is resumed and Paddle creates a transaction to bill for the period ahead.

Related pages