Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing
Search

Pause a subscription

Pause subscriptions when customers want to take a break and come back later. Offering pause functionality alongside cancellation can lower voluntary churn and increase customer LTV.

Pause subscriptions to stop billing for them temporarily. Paddle doesn't bill customers for paused subscriptions until their subscription is 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 new records.

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

How it works

Paddle doesn't create any transactions, invoices, or payments while a subscription is paused. There's no need to create logic to handle this.

Where you've made changes to a subscription and told Paddle to charge or credit later, these are automatically forgiven.

Pauses take effect at the end of a customer's billing period. When you request to pause a subscription, Paddle creates a scheduled change to say the subscription should be paused on the next billing date. On the next billing date, the subscription status changes to paused.

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. We recommend providing a way for customers to resume their subscription in your frontend.

Pause a subscription

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

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

Paddle ID of the subscription entity to work with.

Request

To create an open-ended pause from the next billing period, send an empty request body.

To set a resume date, include the resume_at field in your request.

Response

If successful, Paddle returns the complete subscription entity. The response includes a schedule change to say that the subscription should pause at the end of the billing period.

The end of the billing period is set as the effective_from date for the scheduled change.

Remove a scheduled pause

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

You can't make any changes to a subscription that has a scheduled change against it. This includes adding or removing items, or changing dates.

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

Send a PATCH request to the /subscriptions/{subscription_id} endpoint. In the request body, null the scheduled_change.

Request

Response

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

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 a paused subscription, send a POST request to the /subscriptions/{subscription_id}/resume endpoint.

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

Paddle ID of the subscription entity to work with.

Request

Send an empty request body.

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.

Cancel a paused subscription

To cancel a paused subscription, use the cancel subscription operation. Paused subscriptions are canceled immediately. You can't resume a canceled subscription.

Notifications

subscription.updatedOccurs when Paddle creates a scheduled change for pause.
subscription.pausedOccurs at the end of the billing period when the subscription status changes to paused.
subscription.resumedOccurs when a paused subscription is resumed.
transaction.canceledOccurs if customers have unpaid transactions when the subscription status changes to canceled.

Related pages