Add or remove items from a subscription
Add items to subscriptions when 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 a 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 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 the 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, or the subscription status is
past_due.
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 want to be on the subscription — including existing items. If you don't include an existing item, it's removed from the subscription.
To learn more, see Work with lists
Send a GET request to the /subscriptions/{subscription_id} endpoint.
Paddle ID of the subscription entity to work with.
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 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 a 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 want to add.
You may omit quantity for existing items where you're not making changes to the quantity.
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.
Quantity to bill for.
Paddle ID of an an existing catalog price to bill for.
Add a non-catalog price for a non-catalog product in your catalog to a transaction. In this case, the product and price that you're billing for are specific to this transaction.
Price object for a non-catalog item to bill for. Include a product_id to relate this non-catalog price to an existing catalog price.
Internal description for this price, not shown to customers. Typically notes for your team.
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
How often this price should be charged. null if price is non-recurring (one-time).
Trial period for the product related to this price. The billing cycle begins once the trial period is over. null for no trial period. Requires billing_cycle.
How tax is calculated for this price.
Base price. This price applies to all customers, except for customers located in countries where you have unit_price_overrides.
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
Your own structured key-value data.
Paddle ID for the product that this price is for, prefixed with pro_.
Quantity to bill for.
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 failed payment 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 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 want 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 a customer.
Send the request to apply the changes you previewed. Paddle updates the subscription.
Build request
Build an array of items, with an object containing either:
An item from your catalog
Include a price ID and quantity for each item.
A non-catalog item
Include a price object and quantity for each item.
Non-catalog items are one-off or bespoke items that are specific to that transaction. To learn more, see Bill for non-catalog items
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.
Quantity to bill for.
Paddle ID of an an existing catalog price to bill for.
Add a non-catalog price for a non-catalog product in your catalog to a transaction. In this case, the product and price that you're billing for are specific to this transaction.
Price object for a non-catalog item to bill for. Include a product_id to relate this non-catalog price to an existing catalog price.
Internal description for this price, not shown to customers. Typically notes for your team.
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
How often this price should be charged. null if price is non-recurring (one-time).
Trial period for the product related to this price. The billing cycle begins once the trial period is over. null for no trial period. Requires billing_cycle.
How tax is calculated for this price.
Base price. This price applies to all customers, except for customers located in countries where you have unit_price_overrides.
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
Your own structured key-value data.
Paddle ID for the product that this price is for, prefixed with pro_.
Quantity to bill for.
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 failed payment 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 your pricing is 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 a customer.
Send the request to apply the changes you previewed. Paddle updates the subscription.
Build request
Build an array of items, with an object containing either:
An item from your catalog
Include a price ID and quantity for each item.
A non-catalog item
Include a price object and quantity for each item.
Non-catalog items are one-off or bespoke items that are specific to that transaction. To learn more, see Bill for non-catalog items
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.
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.
Quantity to bill for.
Paddle ID of an an existing catalog price to bill for.
Add a non-catalog price for a non-catalog product in your catalog to a transaction. In this case, the product and price that you're billing for are specific to this transaction.
Price object for a non-catalog item to bill for. Include a product_id to relate this non-catalog price to an existing catalog price.
Internal description for this price, not shown to customers. Typically notes for your team.
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
How often this price should be charged. null if price is non-recurring (one-time).
Trial period for the product related to this price. The billing cycle begins once the trial period is over. null for no trial period. Requires billing_cycle.
How tax is calculated for this price.
Base price. This price applies to all customers, except for customers located in countries where you have unit_price_overrides.
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
Your own structured key-value data.
Paddle ID for the product that this price is for, prefixed with pro_.
Quantity to bill for.
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 failed payment 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. |
