Cancel a subscription
Cancel subscriptions when a customer no longer wants to use your software.
Cancel subscriptions to stop billing for them permanently. Paddle stops billing customers indefinitely.
If a customer just wants to stop using your software temporarily, pause a subscription instead.
Paddle supports subscriptions with multiple products. You can cancel products like recurring addons by removing them. See: Add or remove products on a subscription
How it works
Cancellation take effect at the end of a customer's billing period. When you request to cancel a subscription, Paddle creates a scheduled change to say the subscription should be canceled on the next billing date. On the next billing date, the subscription status changes to canceled
.
You should make sure customers can access your app as normal while they have a scheduled change to cancel against their subscription. After their subscription transitions to cancelled, you should restrict their access.
Paused subscriptions can be canceled immediately, rather than at the end of a customer's billing period.
You can't reactivate a subscription that's canceled.
Reduce active churn with Retain
When customers go to cancel, Retain by Paddle analyzes dozens of data points to salvage that relationship. Smart cancellation flows capture cancellation reason, then suggests other plans, support calls, or a targeted salvage offer.
Cancel a subscription
Send a POST
request to the /subscriptions/{subscription_id}/cancel
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 entity to work with.
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 cancel.
Find the subscription under the Subscriptions heading, then click the … menu and choose Copy ID from the menu.
Request {% id="request-cancel-subscription %}
Send an empty request body.
Response
If successful, Paddle returns the complete subscription entity. The response includes a schedule change to say that the subscription should cancel 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-09-18T16:26:41.252962Z",
20 "ends_at": "2023-10-18T16:26:41.252962Z"
21 },
22 "billing_cycle": {
23 "frequency": 1,
24 "interval": "month"
25 },
26 "scheduled_change": {
27 "action": "cancel",
28 "effective_at": "2023-10-18T16:26:41.252962Z",
29 "resume_at": null
30 },
31 "items": [
32 {
33 "status": "active",
34 "quantity": 10,
35 "recurring": true,
36 "created_at": "2023-08-18T16:25:40.591Z",
Cancel a paused subscription
You can cancel paused subscriptions right away, rather than waiting for the end of the billing period.
Send a POST
request to the /subscriptions/{subscription_id}/cancel
endpoint.
Paddle ID of the subscription entity to work with.
Request
In your body, include effective_from
and set to immediately
.
This field is only valid for subscriptions where the
status
ispaused
. This doesn't include subscriptions that areactive
with a scheduled pause against them.
1231{
2 "effective_from": "immediately"
3}
Response
If successful, Paddle returns a copy of the updated subscription entity. The subscription status is canceled
.
12345678910111213141516171819201{
2 "data": {
3 "id": "sub_01gt25ckjxg1v11jnq9dnrkpfz",
4 "status": "canceled",
5 "customer_id": "ctm_01gt25aq4b2zcfw12szwtjrbdt",
6 "address_id": "add_01gt25aq58yh9ne06zkjvysnaa",
7 "business_id": null,
8 "currency_code": "USD",
9 "created_at": "2023-02-24T16:51:34.109677Z",
10 "updated_at": "2023-09-24T16:57:19.647163Z",
11 "started_at": "2023-02-24T16:51:33.176163Z",
12 "first_billed_at": "2023-02-24T16:51:33.176163Z",
13 "next_billed_at": null,
14 "paused_at": "2023-09-24T16:52:08.390163Z",
15 "canceled_at": "2023-09-24T16:57:19.646163Z",
16 "collection_mode": "automatic",
17 "billing_details": null,
18 "current_billing_period": null,
19 "billing_cycle": {
20 "frequency": 1,
Remove a scheduled cancellation
You can stop a cancellation 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,
Notifications
subscription.updated | Occurs when Paddle creates a scheduled change for pause. |
subscription.canceled | Occurs at the end of the billing period when the subscription status changes to canceled . |
transaction.canceled | Occurs if customers have unpaid transactions when the subscription status changes to canceled. |