Paddle Billing
Search
Home
Concepts
Build
Errors
Webhooks
API Reference
Paddle.js
Changelog
SDKs and Tools
Migrate
Build

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

Pause

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.

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.

To avoid charging for overlapping billing periods, any past due transactions for subscription renewals, where the transaction origin is subscription_recurring, are automatically canceled.

If you've made changes to a subscription or billed for one-time charges and told Paddle to charge on the next billing period:

  • When changes result in a credit, these are automatically forgiven.
  • When changes result in a charge, these are applied to the transaction created on resume.

Resume

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 a subscription resumes, a new billing period for the subscription starts. The current_billing_period.starts_at is set to the date and time that the subscription is resumed, and Paddle creates a transaction to collect for the new billing period immediately.

Before you begin

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

To pause a subscription, you'll need to get the subscription ID for the subscription you want 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 want 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 want 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 

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.

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 

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 the 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 three steps:

  1. Preview resumed subscription

    Preview charging for the subscription. This is optional, but recommended — you should present charge information to a customer if you let them 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.

  3. Update payment method — optional

    For automatically-collected subscriptions, the payment method on file may be expired or no longer valid. Present customers with a way to update their payment method.

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 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. Billing dates on the subscription reflect the resume date, with a new billing cycle starting.

If automatically-collected and collection is successful, or if manually-collected, the subscription status is active. If collection fails, status is past_due and Paddle Retain starts dunning.

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"

Update payment method — optional

When resumed, Paddle creates a transaction to collect for the new billing period. If automatically-collected, Paddle automatically attempts to collect using a payment method on file immediately on resume. This may have expired or no longer be valid, especially when resuming after a long period of time.

If collection fails, the subscription and related transaction become past_due and events for subscription past due occur. As collection is attempted immediately, if a subscription becomes past due then we recommend presenting a way for customers to update their payment method as part of your resume workflow.

Events

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

Related pages

Cancel a subscription
Read more
Provision for subscription pause or resume
Read more
Pause a subscription operation
Read more
On this page

Sign up to get notified when our API evolves

Absolutely no marketing emails, we promise.

Paddle Logo
Privacy
Terms
Paddle.com Market Ltd. © 2012—2024