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
itemslist 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.
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 to get subscriptions for.
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 change.
Find the subscription under the Subscriptions heading, then click the … menu and choose Copy ID from the menu.
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.
212223242526272829303132333435363738394021 },
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.
Add recurring items to a subscription using the API in three steps:
Create an items list that includes existing items and new items, then choose your proration mode.
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.
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.
API
List prices by making a GET request to the /prices endpoint. Work your way through the results to find the price that you'd like to work with.
Dashboard
Head to Paddle > Catalog > Products, click on a product in the list, then click the … menu next to a price and choose Copy ID.
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.
Paddle ID for the price to add to this subscription, prefixed with pri_.
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.
How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.
For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.
When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.
You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.
If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.
How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.
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.
123456789101112131415161{
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.
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_transactionisnull - Paddle calculates proration and charges for them on the next renewal, detailed in
next_transaction
118119120121122123124125126127128129130131132133134135136137118 "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.
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.
12345678910111213141516171819201{
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.
Remove recurring items from a subscription using the API in three steps:
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 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.
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.
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.
Paddle ID for the price to add to this subscription, prefixed with pri_.
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.
How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.
For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.
When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.
You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.
If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.
How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.
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.
12345678910111{
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.
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_transactionisnull - 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.
9394959697989910010110210310410510610710810911011111293 "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.
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.
12345678910111213141516171819201{
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.
Change quantities for recurring items on a subscription using the API in three steps:
Create an items list that includes the items and their new quantities, then choose your proration mode.
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.
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.
API
List prices by making a GET request to the /prices endpoint. Work your way through the results to find the price that you'd like to work with.
Dashboard
Head to Paddle > Catalog > Products, click on a product in the list, then click the … menu next to a price and choose Copy ID.
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.
Paddle ID for the price to add to this subscription, prefixed with pri_.
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.
How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.
For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.
When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.
You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.
If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.
How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.
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.
1234567891011121{
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.
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_immedidately, meaning Paddle calculates proration and charges immediately, detailed immediate_transaction.
177178179180181182183184185186187188189190191192193194195196177 "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.
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.
12345678910111213141516171819201{
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. |
