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

API

Web

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

Pause in two steps:

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.
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 a subscription on the next billing period

Pause a subscription immediately

Pause a subscription with a resume date

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.

Pause a subscription on the next billing period

Pause a subscription immediately

Pause a subscription with a resume date

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.

API

Web

Remove a scheduled pause using the API in two steps:

Build a request
Build a request that removes the scheduled change.
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

1
2
3
1{
2  "scheduled_change": null
3}

Remove scheduled change

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

PATCHhttps://api.paddle.com/subscriptions/{subscription_id}

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

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

200 OK


17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-08T10:38:57.97967Z",
20      "ends_at": "2024-05-08T10:38:57.97967Z"
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": "2024-04-08T10:38:58.673Z",
33        "updated_at": "2024-04-08T10:38:58.673Z",
34        "previously_billed_at": "2024-04-08T10:38:57.97967Z",
35        "next_billed_at": "2024-05-08T10:38:57.97967Z",
36        "trial_dates": null,

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.

API

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

Build a request
Build a request that includes the new resume date.
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

1
2
3
1{
2  "effective_from": "2023-11-01T00:00:00.000000Z"
3}

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.

200 OK


14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
14    "paused_at": "2023-10-21T11:32:03.228295Z",
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": null,
19    "billing_cycle": {
20      "frequency": 1,
21      "interval": "month"
22    },
23    "scheduled_change": {
24      "action": "resume",
25      "effective_at": "2023-11-01T00:00:00Z",
26      "resume_at": null
27    },
28    "items": [
29      {
30        "status": "inactive",
31        "quantity": 30,
32        "recurring": true,
33        "created_at": "2023-08-21T11:31:10.292Z",

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)

API

Web

Resume a paused subscription using the API in two steps:

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

GEThttps://api.paddle.com/subscriptions/{subscription_id}?include=recurring_transaction_details

subscription_idstring

Paddle ID of the subscription entity to work with.

includearray[string]

Include related entities in the response. Use a comma-separated list to specify multiple entities.

Response

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

200 OK


14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
14    "paused_at": "2023-10-27T11:32:34.146969Z",
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": null,
19    "billing_cycle": {
20      "frequency": 1,
21      "interval": "month"
22    },
23    "recurring_transaction_details": {
24      "tax_rates_used": [
25        {
26          "tax_rate": "0.08875",
27          "totals": {
28            "subtotal": "40000",
29            "discount": "0",
30            "tax": "3549",
31            "total": "43549"
32          }
33        }

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.

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01hv959anj4zrw503h2acawb3p",
4    "status": "active",
5    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
6    "address_id": "add_01hv958rbhm5n0r6h3tmna4gtv",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-04-12T12:42:27.89Z",
10    "updated_at": "2024-04-12T12:44:51.309Z",
11    "started_at": "2024-04-12T12:42:27.185672Z",
12    "first_billed_at": "2024-04-12T12:42:27.185672Z",
13    "next_billed_at": "2024-05-12T12:44:51.27Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-12T12:44:51.27Z",
20      "ends_at": "2024-05-12T12:44:51.27Z"

Events

For a full list of events that occur when a subscription is paused or resumed, see: Subscription pause or resume

Cancel a subscription

Provision for subscription pause or resume

Pause a subscription operation

Sign up to get notified when our API evolves