Add or remove items from a subscription

Add items to subscriptions when your customers want to take additional users, modules, or other kinds of recurring addons. Remove items when customers want to change or cancel them.

Paddle supports multi-product subscriptions, letting you build complex pricing models. Add or remove items from a subscription to make changes to customer plans.

Add or remove items from a subscription when:

Customers pay per user, and they add users to their subscription
A customer wants to stop paying for ("cancel") an additional recurring product, like a reporting module
You have a tiered or volume pricing model and need to set the tier to bill for

You can add items, remove items, and change quantities in the same request. We've split them into separate examples here for simplicity.

How it works

You might have a subscription billing model that's made up of multiple components. For example, you might offer a base plan and additional modules or users.

In Paddle, you don't need to create multiple subscriptions for multiple products. Each subscription holds an items list that can contain multiple products. When your customer does something like takes on a new module or decreases their user count, you can make changes to the items list on their subscription bill for the changes.

Keep in mind that your customers might say:

They're "canceling" a product, like a module or other recurring addon, when they'd like to remove it. Canceling items doesn't cancel a subscription entirely.
They're "subscribing" or "upgrading" when they add a product or change quantities. You don't need to create a new subscription to bill for new products.

Recurring items on a subscription must have the same billing interval. For example, you can't have a subscription with some prices that are billed monthly and some products that are billed annually.

Proration

When you make changes to items, you can determine how Paddle should bill for those changes. This is called proration. Paddle's subscription billing engine calculates proration to the minute, allowing for precise billing.

Before you add or remove items on a subscription, you can preview the changes first. This lets you see prorated charges for any changes that you're making before charging for them. You might present this to your customer in your frontend.

Related subscription changes

Adding or removing items is typically used when you want to make changes to recurring addons, like optional modules or seats.

Depending on what you're looking to do, you might also like to:

Replace items to upgrade or downgrade a subscription
Upgrading or downgrading a subscription plan typically involves replacing products. For example, you might replace a "Starter plan" product with a "Premium plan" product to upgrade.
Create one-time charges for non-recurring items
One-time charges aren't included in the items list for a subscription, since they aren't recurring. Create a one-time charge instead. For example, you might bill for an "Out of hours support incident" as and when it happens.

Before you begin

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

Get subscription and extract existing prices

If you're working with the API, you'll need to get and extract existing items on a subscription first.

This is because when updating subscription items, Paddle expects the complete list of items that you'd like to be on the subscription — including existing items. If you don't include an existing item, it's removed from the subscription.

See: Work with lists

Send a GET request to the /subscriptions/{subscription_id} endpoint.

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

subscription_idstring

Paddle ID of the subscription entity to work with.

Find subscription ID

Response

Paddle returns the complete subscription entity for the ID you specified.

Extract the price ID from the price object and the quantity for each item in the items array. Keep those for the next step.

200 OK


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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-06-22T08:25:14.287456Z",
33        "updated_at": "2023-06-22T08:25:14.287456Z",
34        "previously_billed_at": "2023-06-22T08:25:12.565118Z",
35        "next_billed_at": "2023-07-22T08:25:12.565118Z",
36        "price": {
37          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
38          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
39          "description": "Monthly (per seat)",
40          "tax_mode": "account_setting",

Add items to a subscription

Add items to subscriptions when your customers want to take additional modules or services. They might call this "upgrading."

You can only add recurring items. Recurring items are prices that have a billing_cycle set against them.

You can use any proration billing mode.

Recurring items on a subscription must have the same billing interval. For example, you can't have a subscription with some products that are billed monthly and some products that are billed annually.

API

Web

Add recurring items to a subscription using the API in three steps:

Build a request
Create an items list that includes existing items and new items, then choose your proration mode.
Preview your changes
Preview the impact of the new items on the regular amount the customer pays and the next renewal, as well as any immediate charges. This is optional, but recommended — you should present charge information to your customer.
Update the subscription
Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build a request that includes an items array. Your array should include an object for each item, where each object contains a price ID and a quantity.

Include existing price IDs that you extracted in the previous step, as well as any new items that you'd like to add.

You may omit quantity for existing items where you're not making changes to the quantity.

Find price ID

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

price_idstring

Paddle ID for the price to add to this subscription, prefixed with pri_.

quantitynumber

Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the added items.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

Request

This example adds two new items with a quantity of 1 each. There's no quantity for the final item because it already exists on the subscription. Its quantity won't be changed.

It includes prorated_immediately as the billing mode, meaning Paddle calculates a prorated charge for the new items and bills for it on the next renewal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
1{
2  "proration_billing_mode": "prorated_next_billing_period",
3  "items": [
4    {
5      "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
6      "quantity": 1
7    },
8    {
9      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
10      "quantity": 1
11    },
12    {
13      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
14    }
15  ]
16}

Preview change

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

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

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Previews include immediate_transaction, next_transaction, and recurring_transaction_details that give you information about upcoming transactions impacted as a result of this change. In this example, proration_billing_mode is prorated_next_billing, meaning:

Paddle doesn't create a charge immediately, so immediate_transaction is null
Paddle calculates proration and charges for them on the next renewal, detailed in next_transaction

200 OK


118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
118          "unit_totals": {
119            "subtotal": "28500",
120            "discount": "0",
121            "tax": "2529",
122            "total": "31029"
123          }
124        }
125      ]
126    },
127    "next_transaction": {
128      "billing_period": {
129        "starts_at": "2023-07-22T08:25:12.565118Z",
130        "ends_at": "2023-08-22T08:25:12.565118Z"
131      },
132      "details": {
133        "tax_rates_used": [
134          {
135            "tax_rate": "0.08875",
136            "totals": {
137              "subtotal": "106996",

Update subscription

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 returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

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_01h3h3a9sfpr5syq38tq0sd4sp",
4    "status": "active",
5    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-06-22T08:25:14.287455Z",
10    "updated_at": "2023-06-22T08:40:46.295638Z",
11    "started_at": "2023-06-22T08:25:12.565118Z",
12    "first_billed_at": "2023-06-22T08:25:12.565118Z",
13    "next_billed_at": "2023-07-22T08:25:12.565118Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2023-06-22T08:25:12.565118Z",
20      "ends_at": "2023-07-22T08:25:12.565118Z"

Remove items from a subscription

Remove items from subscriptions when your customers no longer want additional modules or other addons. They might call this "canceling" those modules or addons.

Depending on your pricing model, you might also do this as part of an upgrade or downgrade workflow, too. For example, some items might be incompatible with entry-level plans, or might be included in higher-level plans.

You can choose any proration billing mode.

API

Web

Remove recurring items from a subscription using the API in three steps:

Build a request
Create an items list that has the list of items that you'd like to keep on the subscription, then choose your proration mode.
Preview your changes
Preview the impact of removing the items on the regular amount the customer pays and the next renewal. This is optional, but recommended — you should present charge information to your customer.
Update the subscription
Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build a request that includes an items array. Your array should include an object for each item, where each object contains a price ID and a quantity.

To remove items, don't include them in the array.

You may omit quantity for existing items where you're not making changes to the quantity.

Subscriptions must have at least one item. Consider canceling a subscription entirely, or pausing to stop billing temporarily.

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

price_idstring

Paddle ID for the price to add to this subscription, prefixed with pri_.

quantitynumber

Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the removed items.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

Request

This example includes two items with a quantity of 1 each. There's no quantity for either item because they already exist on the subscription. Their quantities won't be changed.

It includes prorated_next_billing as the billing mode, meaning Paddle calculates a prorated credit for the removed items and applies it to the next transaction.

1
2
3
4
5
6
7
8
9
10
11
1{
2  "proration_billing_mode": "prorated_next_billing_period",
3  "items": [
4    {
5      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
6    },
7    {
8      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
9    }
10  ]
11}

Preview change

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

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

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Paddle doesn't create a charge immediately, so immediate_transaction is null
Paddle calculates proration and charges for them on the next renewal, detailed in next_transaction

As an item was removed, Paddle calculates a credit and deducts this from the next renewal.

200 OK


93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
93          "unit_totals": {
94            "subtotal": "10000",
95            "discount": "0",
96            "tax": "887",
97            "total": "10887"
98          }
99        }
100      ]
101    },
102    "next_transaction": {
103      "billing_period": {
104        "starts_at": "2023-08-22T08:25:12.565118Z",
105        "ends_at": "2023-09-22T08:25:12.565118Z"
106      },
107      "details": {
108        "tax_rates_used": [
109          {
110            "tax_rate": "0.08875",
111            "totals": {
112              "subtotal": "40000",

Update subscription

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

Response

If successful, Paddle returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

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_01h3h3a9sfpr5syq38tq0sd4sp",
4    "status": "active",
5    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-06-22T08:25:14.287455Z",
10    "updated_at": "2023-07-22T09:33:24.427246Z",
11    "started_at": "2023-06-22T08:25:12.565118Z",
12    "first_billed_at": "2023-06-22T08:25:12.565118Z",
13    "next_billed_at": "2023-08-22T08:25:12.565118Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2023-07-22T08:25:12.565118Z",
20      "ends_at": "2023-08-22T08:25:12.565118Z"

Change quantities

Change quantities when customers want to increase or decrease the number of units of an item that they pay for. You might change quantities if you bill per user or seat. They might call it "upgrading" when increasing units, and "downgrading" when decreasing units.

You can choose any proration billing mode.

API

Web

Change quantities for recurring items on a subscription using the API in three steps:

Build a request
Create an items list that includes the items and their new quantities, then choose your proration mode.
Preview your changes
Preview the impact of the changed quantities on the regular amount the customer pays and the next renewal, as well as any immediate charges. This is optional, but recommended — you should present charge information to your customer.
Update the subscription
Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build a request that includes an items array. Your array should include an object for each item, where each object contains a price ID and a quantity.

If you're just changing quantities, your items array should include the same price IDs with different quantities.

You may omit quantity for existing items where you're not making changes to the quantity.

Find price ID

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

price_idstring

Paddle ID for the price to add to this subscription, prefixed with pri_.

quantitynumber

Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the quantity changes.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

Request

This example includes two items. There's no quantity for the first item, which already exists on the subscription. Its quantity won't be changed. The quantity for the second item has been increased to 30 from 10.

It includes prorated_immediately as the billing mode, meaning Paddle calculates a prorated charge for the additional units and bills for it on the next renewal.

1
2
3
4
5
6
7
8
9
10
11
12
1{
2  "proration_billing_mode": "prorated_immediately",
3  "items": [
4    {
5      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
6    },
7    {
8      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
9      "quantity": 30
10    }
11  ]
12}

Preview change

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

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

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

200 OK


177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
177              "discount": "0",
178              "tax": "887",
179              "total": "10887"
180            }
181          }
182        ]
183      },
184      "adjustments": []
185    },
186    "immediate_transaction": {
187      "billing_period": {
188        "starts_at": "2023-08-22T08:28:31.678675268Z",
189        "ends_at": "2023-09-22T08:25:12.565118Z"
190      },
191      "details": {
192        "tax_rates_used": [
193          {
194            "tax_rate": "0.08875",
195            "totals": {
196              "subtotal": "89994",

Update subscription

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

Response

If successful, Paddle returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

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_01h3h3a9sfpr5syq38tq0sd4sp",
4    "status": "active",
5    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-06-22T08:25:14.287455Z",
10    "updated_at": "2023-08-22T08:32:24.559129Z",
11    "started_at": "2023-06-22T08:25:12.565118Z",
12    "first_billed_at": "2023-06-22T08:25:12.565118Z",
13    "next_billed_at": "2023-09-22T08:25:12.565118Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2023-08-22T08:25:12.565118Z",
20      "ends_at": "2023-09-22T08:25:12.565118Z"

Events

`subscription.updated`	Occurs when you update items on a subscription.
`adjustment.created`	Occurs when you choose a proration billing mode that prorates and bills for changes immediately.
`transaction.created`	Occurs when you choose a proration billing mode that bills the customer for changes immediately.

Bill for one-time charges

Upgrade or downgrade

Proration

Sign up to get notified when our API changes