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.
Paddle ID of the subscription entity to work with.
API
List subscriptions by making a GET request to the /subscriptions endpoint. Work your way through the results to find the subscriptions that you'd like to work with.
Use the customer_id parameter to return only subscriptions for a specific customer.
Paddle ID of the customer to get subscriptions for.
Customers may have more than one subscription, so check the details of each returned subscription to find the one you'd like to pause.
Dashboard
Head to Paddle > Customers, and find the customer whose subscription you'd like to pause.
Find the subscription under the Subscriptions heading, then click the … menu and choose Copy ID from the menu.
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.
12341{
2 "effective_from": "next_billing_period",
3 "resume_at": "2023-10-09T16:30:00Z"
4}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.
171819202122232425262728293031323334353617 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-08-18T16:25:38.870962Z",
20 "ends_at": "2023-09-18T16:25:38.870962Z"
21 },
22 "billing_cycle": {
23 "frequency": 1,
24 "interval": "month"
25 },
26 "scheduled_change": {
27 "action": "pause",
28 "effective_at": "2023-09-18T16:25:38.870962Z",
29 "resume_at": "2023-10-09T16:30:00Z"
30 },
31 "items": [
32 {
33 "status": "active",
34 "quantity": 10,
35 "recurring": true,
36 "created_at": "2023-08-18T16:25:40.591Z",
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.
Paddle ID of the subscription entity to work with.
Request
1231{
2 "scheduled_change": null
3}Response
If successful, Paddle responds with the updated subscription entity. Scheduled change is set to null and the status is active.
171819202122232425262728293031323334353617 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-08-18T16:25:38.870962Z",
20 "ends_at": "2023-09-18T16:25:38.870962Z"
21 },
22 "billing_cycle": {
23 "frequency": 1,
24 "interval": "month"
25 },
26 "scheduled_change": null,
27 "items": [
28 {
29 "status": "active",
30 "quantity": 10,
31 "recurring": true,
32 "created_at": "2023-08-18T16:25:40.591Z",
33 "updated_at": "2023-08-18T16:25:40.591Z",
34 "previously_billed_at": "2023-08-18T16:25:38.870962Z",
35 "next_billed_at": "2023-09-18T16:25:38.870962Z",
36 "trial_dates": null,
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.
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.
12345678910111213141516171819201{
2 "data": {
3 "id": "sub_01h84qezffcfrjx275ve304rt0",
4 "status": "active",
5 "customer_id": "ctm_01h82et3vctdaapjzerb3xrkex",
6 "address_id": "add_01h84qdjewtveve149393qfqcz",
7 "business_id": null,
8 "currency_code": "USD",
9 "created_at": "2023-08-18T16:25:40.591Z",
10 "updated_at": "2023-09-18T16:26:41.257962Z",
11 "started_at": "2023-08-18T16:25:38.870962Z",
12 "first_billed_at": "2023-08-18T16:25:38.870962Z",
13 "next_billed_at": "2023-10-18T16:26:41.252962Z",
14 "paused_at": null,
15 "canceled_at": null,
16 "collection_mode": "automatic",
17 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-09-18T16:26:41.252962Z",
20 "ends_at": "2023-10-18T16:26:41.252962Z"
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.updated | Occurs when Paddle creates a scheduled change for pause. |
subscription.paused | Occurs at the end of the billing period when the subscription status changes to paused. |
subscription.resumed | Occurs when a paused subscription is resumed. |
transaction.canceled | Occurs if customers have unpaid transactions when the subscription status changes to canceled. |
