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 topaused
.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:
Build a request that includes
effective_from
andresume_at
to tell Paddle when you'd like a subscription to pause and resume.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.
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.
RFC 3339 datetime string of when the paused subscription should resume. Omit to pause indefinitely until resumed.
Request
This example pauses a subscription on the next billing period. Paddle creates a scheduled change with an effective_at
date of the next_billed_at
date for the subscription.
It's an open-ended pause, since there's no resume_at
date set.
1231{
2 "effective_from": "next_billing_period"
3}
Request
This example pauses a subscription right away. The subscription status
changes to paused
.
It's an open-ended pause, since there's no resume_at
date set.
1231{
2 "effective_from": "immediately"
3}
Request
This example pauses a subscription right away. The subscription status
changes to paused
.
A resume_at
date is included with the request, so Paddle creates a scheduled_change
to resume with an effective_at
of the resume date included with the request. The subscription automatically resumes on this date.
12341{
2 "effective_from": "immediately",
3 "resume_at": "2023-11-01T00:00:00Z"
4}
Pause subscription
Send a POST
request to the /subscriptions/{subscription_id}/pause
endpoint with the request you built.
Paddle ID of the subscription entity to work with.
Response
If successful, Paddle returns a copy of the subscription entity with a scheduled change to pause.
There's no resume_at
date for the scheduled change because it's an open-ended pause. next_billed_at
is null
as the subscription is not set to be billed again until explicitly resumed.
171819202122232425262728293031323334353617 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-09-21T11:31:08.689295Z",
20 "ends_at": "2023-10-21T11:31:08.689295Z"
21 },
22 "billing_cycle": {
23 "frequency": 1,
24 "interval": "month"
25 },
26 "scheduled_change": {
27 "action": "pause",
28 "effective_at": "2023-10-21T11:31:08.689295Z",
29 "resume_at": null
30 },
31 "items": [
32 {
33 "status": "active",
34 "quantity": 30,
35 "recurring": true,
36 "created_at": "2023-08-21T11:31:10.292Z",
Response
If successful, Paddle returns a copy of the subscription entity with the status
of paused
.
12345678910111213141516171819201{
2 "data": {
3 "id": "sub_01hbxebsqc7qg1fbqg5eqz1v82",
4 "status": "paused",
5 "customer_id": "ctm_01hbxeaqa73chfk9ants8gtrjf",
6 "address_id": "add_01hbxeaqb46zke464dwjjh7zab",
7 "business_id": null,
8 "currency_code": "USD",
9 "created_at": "2023-10-04T13:34:45.484Z",
10 "updated_at": "2023-10-05T10:03:01.546Z",
11 "started_at": "2023-10-04T13:34:44.39169Z",
12 "first_billed_at": "2023-10-04T13:34:44.39169Z",
13 "next_billed_at": null,
14 "paused_at": "2023-10-05T10:03:01.544Z",
15 "canceled_at": null,
16 "collection_mode": "automatic",
17 "billing_details": null,
18 "current_billing_period": null,
19 "billing_cycle": {
20 "frequency": 1,
Response
If successful, Paddle returns a copy of the subscription entity with the status
of paused
.
It includes a scheduled_change
to resume effective the resume_at
date that you sent in your request.
141516171819202122232425262728293031323314 "paused_at": "2023-10-05T12:50:16.963Z",
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": "active",
31 "quantity": 10,
32 "recurring": true,
33 "created_at": "2023-10-05T12:43:53.059Z",
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:
Build a request that removes the 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
.
Change that's scheduled to be applied to a subscription. null
if no scheduled changes.
Request
1231{
2 "scheduled_change": null
3}
Remove scheduled change
Send a PATCH
request to the /subscriptions/{subscription_id}
endpoint with the request you built.
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
.
171819202122232425262728293031323334353617 "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.
Set or change the resume date for a paused subscription using the API in two steps:
Build a request that includes the new 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.
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
1231{
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.
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.
141516171819202122232425262728293031323314 "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)
Resume a paused subscription using the API in two steps:
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.
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
.
Paddle ID of the subscription entity to work with.
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.
141516171819202122232425262728293031323314 "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.
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.
12345678910111213141516171819201{
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