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 theitemslist 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.
To add or remove items from a subscription, you'll need to get the subscription ID for the subscription you want to change.
You can use the status query parameter when listing with the value trialing to get a list of subscriptions in trial.
Add items to a subscription
Recurring items on subscription must have the same billing interval. For example, you can't have subscription with some prices that are billed monthly and some products that are billed annually.
Add recurring items to subscriptions when customers want to take additional modules or services. They might call this "upgrading."
You can use any proration billing mode.
- Go to Paddle > Customers.
- Find the customer whose subscription you want to add an item to, then click them to open the customer page.
- Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
- From the subscription overview page, click Edit subscription
- Click the Add line item link to add items new items to the items list. Choose a product, related price, and quantity for each item.
- Choose a product, related price, and quantity for each item.
- Choose whether to bill for the prorated amount or full amount, and when it should be charged.
- If you don't want to bill for these changes at all, toggle Charge for what's remaining of the current billing period? off.
- Click Continue to review.
- Review the summary of your changes.
- Click Save to apply your changes.
Add items to a subscription using the API in three steps:
- Extract existing items
Get the existing items on the subscription to extract theprice.idandquantityfor each item. - Preview change Optional
Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to update items. - Update subscription
Send a request to update the subscription with the changes you previewed.
Extract existing items
Send a GET request to the /subscriptions/{subscription_id} endpoint to get the existing items on the subscription. Extract the price.id and quantity for each item in the items array — you'll need these to build your update request.
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
Preview change Optional
Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint to preview the changes you're making to the subscription.
In your request, include an an items array with an object containing a price_id and quantity for each item you want on the subscription — include existing items you want to keep, plus any new ones. Omit quantity for existing items where you're not changing the amount.
Include proration_billing_mode to tell Paddle how to bill for the changes. For prorated_immediately or full_immediately on automatically-collected subscriptions, Paddle tries to collect right away. Optionally, include on_payment_failure to control payment failure behavior (defaults to prevent_change).
This example adds two new items with quantity: 1 each. The existing item has no quantity so it stays unchanged. proration_billing_mode is prorated_next_billing_period.
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. In this example, proration_billing_mode is prorated_next_billing_period, so immediate_transaction is null and proration is charged on the next renewal.
You should present this to customers if you offer an in-app workflow to update items.
{ "proration_billing_mode": "prorated_next_billing_period", "items": [ { "price_id": "pri_01gsz95g2zrkagg294kpstx54r", "quantity": 1 }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1 }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke" } ]}{ "data": { "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-06-22T08:30:27.133418Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-07-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-06-22T08:25:12.565118Z", "ends_at": "2023-07-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "recurring_transaction_details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "68500", "discount": "0", "tax": "6078", "total": "74578" } } ], "totals": { "subtotal": "68500", "tax": "6078", "discount": "0", "total": "74578", "fee": null, "credit": "0", "balance": "74578", "grand_total": "74578", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } }, { "price_id": "pri_01gsz95g2zrkagg294kpstx54r", "quantity": 1, "totals": { "subtotal": "28500", "tax": "2529", "discount": "0", "total": "31029" }, "product": { "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "name": "Reporting module", "description": "Get access to comprehensive reports and customizable analytics dashboards.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "28500", "discount": "0", "tax": "2529", "total": "31029" } } ] }, "next_transaction": { "billing_period": { "starts_at": "2023-07-22T08:25:12.565118Z", "ends_at": "2023-08-22T08:25:12.565118Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "106996", "discount": "0", "tax": "9494", "total": "116490" } } ], "totals": { "subtotal": "106996", "tax": "9494", "discount": "0", "total": "116490", "fee": null, "credit": "0", "balance": "116490", "grand_total": "116490", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } }, { "price_id": "pri_01gsz95g2zrkagg294kpstx54r", "quantity": 1, "totals": { "subtotal": "28500", "tax": "2529", "discount": "0", "total": "31029" }, "product": { "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "name": "Reporting module", "description": "Get access to comprehensive reports and customizable analytics dashboards.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "28500", "discount": "0", "tax": "2529", "total": "31029" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "9999", "tax": "887", "discount": "0", "total": "10886" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "9999", "discount": "0", "tax": "887", "total": "10886" }, "proration": { "rate": "0.99988", "billing_period": { "starts_at": "2023-06-22T08:30:27.123319Z", "ends_at": "2023-07-22T08:25:12.565118Z" } } }, { "price_id": "pri_01gsz95g2zrkagg294kpstx54r", "quantity": 1, "totals": { "subtotal": "28497", "tax": "2529", "discount": "0", "total": "31026" }, "product": { "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "name": "Reporting module", "description": "Get access to comprehensive reports and customizable analytics dashboards.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "28497", "discount": "0", "tax": "2529", "total": "31026" }, "proration": { "rate": "0.99988", "billing_period": { "starts_at": "2023-06-22T08:30:27.125971Z", "ends_at": "2023-07-22T08:25:12.565118Z" } } } ] }, "adjustments": [] }, "immediate_transaction": null, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-06-22T08:25:14.287456Z", "previously_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:30:26.695165Z", "updated_at": "2023-06-22T08:30:26.695165Z", "previously_billed_at": null, "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:30:26.695175Z", "updated_at": "2023-06-22T08:30:26.695175Z", "previously_billed_at": null, "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01gsz95g2zrkagg294kpstx54r", "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "31029", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "814c42dc-eb30-4840-a637-29b6df8e9bac" }}Update subscription
Send a PATCH request to the /subscriptions/{subscription_id} endpoint to update the subscription.
In your request, include the same body as the preview request.
Paddle updates the subscription.
{ "proration_billing_mode": "prorated_next_billing_period", "items": [ { "price_id": "pri_01gsz95g2zrkagg294kpstx54r", "quantity": 1 }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1 }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke" } ]}{ "data": { "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp", "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-06-22T08:40:46.295638Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-07-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-06-22T08:25:12.565118Z", "ends_at": "2023-07-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-06-22T08:25:14.287456Z", "previously_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808402Z", "updated_at": "2023-06-22T08:40:45.808402Z", "previously_billed_at": null, "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808418Z", "updated_at": "2023-06-22T08:40:45.808418Z", "previously_billed_at": null, "next_billed_at": "2023-07-22T08:25:12.565118Z", "price": { "id": "pri_01gsz95g2zrkagg294kpstx54r", "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "31029", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "1ce4f946-eeb6-4369-a170-a9c79a88455c" }}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.
- Go to Paddle > Customers.
- Find the customer whose subscription you want to remove an item from, then click them to open the customer page.
- Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
- From the subscription overview page, click Edit subscription
- Click the button next to an item in the list, then choose Remove item from the menu.
- Choose whether to credit the prorated or full amount, and when to issue it.
- If you don't want to credit for these changes at all, toggle Issue credit for what's remaining of the current billing period? off.
- Click Continue to review.
- Review the summary of your changes.
- Click Save to apply your changes.
Remove items from a subscription using the API in three steps:
- Extract existing items
Get the existing items on the subscription to extract theprice.idandquantityfor each item. - Preview change Optional
Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to update items. - Update subscription
Send a request to update the subscription with the changes you previewed.
Extract existing items
Send a GET request to the /subscriptions/{subscription_id} endpoint to get the existing items on the subscription. Extract the price.id and quantity for each item in the items array — you'll need these to build your update request.
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
Preview change Optional
Subscriptions must have at least one item. Consider canceling a subscription entirely, or pausing to stop billing temporarily.
Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint to preview the changes you're making to the subscription.
Include an items array with price IDs and quantities for items you want to keep — omit any items you want to remove.
Include proration_billing_mode to determine how to credit the removed items. Optionally, include on_payment_failure to control payment failure behavior (defaults to prevent_change).
This example keeps two items and removes the third by omitting it. proration_billing_mode is prorated_next_billing_period, so Paddle credits the removed item on the next renewal.
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. In this example, proration_billing_mode is prorated_next_billing_period, so immediate_transaction is null and Paddle calculates a credit deducted from the next renewal.
{ "proration_billing_mode": "prorated_next_billing_period", "items": [ { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2" }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke" } ]}{ "data": { "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-07-22T09:25:32.374176Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-07-22T08:25:12.565118Z", "ends_at": "2023-08-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "recurring_transaction_details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "40000", "discount": "0", "tax": "3549", "total": "43549" } } ], "totals": { "subtotal": "40000", "tax": "3549", "discount": "0", "total": "43549", "fee": null, "credit": "0", "balance": "43549", "grand_total": "43549", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } } ] }, "next_transaction": { "billing_period": { "starts_at": "2023-08-22T08:25:12.565118Z", "ends_at": "2023-09-22T08:25:12.565118Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "40000", "discount": "0", "tax": "3549", "total": "43549" } } ], "totals": { "subtotal": "40000", "tax": "3549", "discount": "0", "total": "43549", "fee": null, "credit": "30987", "balance": "12562", "grand_total": "12562", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } } ] }, "adjustments": [ { "transaction_id": "txn_01h3h4j5hj2cfzme5pscbvapb5", "items": [ { "item_id": "txnitm_01h3h4j5zymz2d2sncvmk78ns4", "type": "proration", "amount": "30987", "proration": { "rate": "0.99866", "billing_period": { "starts_at": "2023-07-22T09:25:32.373183Z", "ends_at": "2023-08-22T08:25:12.565118Z" } }, "totals": { "subtotal": "28461", "tax": "2526", "total": "30987" } } ], "totals": { "subtotal": "28461", "tax": "2526", "total": "30987", "fee": "1563", "earnings": "26898", "currency_code": "USD" } } ] }, "immediate_transaction": null, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-07-22T08:25:36.112473Z", "previously_billed_at": "2023-07-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808402Z", "updated_at": "2023-07-22T08:25:36.114303Z", "previously_billed_at": "2023-07-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "912bdd81-ee77-4c3c-b666-3d03cc765c0c" }}Update subscription
Send a PATCH request to the /subscriptions/{subscription_id} endpoint to update the subscription.
In your request, include the same body as the preview request.
Paddle updates the subscription.
{ "proration_billing_mode": "prorated_next_billing_period", "items": [ { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2" }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke" } ]}{ "data": { "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp", "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-07-22T09:33:24.427246Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-07-22T08:25:12.565118Z", "ends_at": "2023-08-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-07-22T08:25:36.112473Z", "previously_billed_at": "2023-07-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808402Z", "updated_at": "2023-07-22T08:25:36.114303Z", "previously_billed_at": "2023-07-22T08:25:12.565118Z", "next_billed_at": "2023-08-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "fe11c394-3431-477f-a3ac-a63da6704545" }}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.
- Go to Paddle > Customers.
- Find the customer whose subscription you want to change quantities for items on, then click them to open the customer page.
- Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
- From the subscription overview page, click Edit subscription
- Make changes to quantities in the items list.
- Depending on the changes you made, choose to either credit or charge for the prorated or full amount, and charge or issue for it now or later.
- If you don't want these changes to be charged or credited at all, toggle the proration option off.
- Click Continue to review.
- Review the summary of your changes.
- Click Save to apply your changes.
Change quantities on a subscription using the API in three steps:
- Extract existing items
Get the existing items on the subscription to extract theprice.idandquantityfor each item. - Preview change Optional
Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to update items. - Update subscription
Send a request to update the subscription with the changes you previewed.
Extract existing items
Send a GET request to the /subscriptions/{subscription_id} endpoint to get the existing items on the subscription. Extract the price.id and quantity for each item in the items array — you'll need these to build your update request.
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
Preview change Optional
Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint to preview the changes you're making to the subscription.
Include an items array with the same price IDs and updated quantities. You can omit quantity for items you're not changing.
Include proration_billing_mode to tell Paddle how to bill for the quantity changes. For prorated_immediately or full_immediately on automatically-collected subscriptions, Paddle tries to collect right away. Optionally, include on_payment_failure to control payment failure behavior (defaults to prevent_change).
This example increases seats from 10 to 30. The voice rooms addon has no quantity so it stays unchanged.
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. In this example, proration_billing_mode is prorated_immediately, so Paddle calculates and charges proration right away, detailed in immediate_transaction.
{ "proration_billing_mode": "prorated_immediately", "items": [ { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2" }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30 } ]}{ "data": { "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-08-22T08:28:30.220384Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-08-22T08:25:12.565118Z", "ends_at": "2023-09-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "recurring_transaction_details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "100000", "discount": "0", "tax": "8874", "total": "108874" } } ], "totals": { "subtotal": "100000", "tax": "8874", "discount": "0", "total": "108874", "fee": null, "credit": "0", "balance": "108874", "grand_total": "108874", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30, "totals": { "subtotal": "90000", "tax": "7987", "discount": "0", "total": "97987" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } } ] }, "next_transaction": { "billing_period": { "starts_at": "2023-09-22T08:25:12.565118Z", "ends_at": "2023-10-22T08:25:12.565118Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "100000", "discount": "0", "tax": "8874", "total": "108874" } } ], "totals": { "subtotal": "100000", "tax": "8874", "discount": "0", "total": "108874", "fee": null, "credit": "0", "balance": "108874", "grand_total": "108874", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30, "totals": { "subtotal": "90000", "tax": "7987", "discount": "0", "total": "97987" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" } }, { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" } } ] }, "adjustments": [] }, "immediate_transaction": { "billing_period": { "starts_at": "2023-08-22T08:28:31.678675268Z", "ends_at": "2023-09-22T08:25:12.565118Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "89994", "discount": "0", "tax": "7987", "total": "97981" } } ], "totals": { "subtotal": "89994", "tax": "7987", "discount": "0", "total": "97981", "fee": null, "credit": "32660", "balance": "65321", "grand_total": "65321", "earnings": null, "currency_code": "USD" }, "line_items": [ { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30, "totals": { "subtotal": "89994", "tax": "7987", "discount": "0", "total": "97981" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" }, "proration": { "rate": "0.99993", "billing_period": { "starts_at": "2023-08-22T08:28:30.2190671Z", "ends_at": "2023-09-22T08:25:12.565118Z" } } } ] }, "adjustments": [ { "transaction_id": "txn_01h3h8qvbbgsvvakck3w432t7p", "items": [ { "item_id": "txnitm_01h3h8qvs7cmyyb9fs92hqbzdh", "type": "proration", "amount": "32660", "proration": { "rate": "0.99993", "billing_period": { "starts_at": "2023-08-22T08:28:30.217459Z", "ends_at": "2023-09-22T08:25:12.565118Z" } }, "totals": { "subtotal": "29998", "tax": "2662", "total": "32660" } } ], "totals": { "subtotal": "29998", "tax": "2662", "total": "32660", "fee": "1670", "earnings": "28328", "currency_code": "USD" } } ] }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 30, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-08-22T08:28:30.210601Z", "previously_billed_at": "2023-08-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808402Z", "updated_at": "2023-08-22T08:26:06.361047Z", "previously_billed_at": "2023-08-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "16c114e9-1966-41fd-b64c-44d3901ca0c2" }}Update subscription
{ "proration_billing_mode": "prorated_immediately", "items": [ { "price_id": "pri_01h1vjfevh5etwq3rb416a23h2" }, { "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 30 } ]}{ "data": { "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp", "status": "active", "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a", "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5", "business_id": null, "currency_code": "USD", "created_at": "2023-06-22T08:25:14.287455Z", "updated_at": "2023-08-22T08:32:24.559129Z", "started_at": "2023-06-22T08:25:12.565118Z", "first_billed_at": "2023-06-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-08-22T08:25:12.565118Z", "ends_at": "2023-09-22T08:25:12.565118Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 30, "recurring": true, "created_at": "2023-06-22T08:25:14.287456Z", "updated_at": "2023-08-22T08:32:24.552996Z", "previously_billed_at": "2023-08-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3266", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-06-22T08:40:45.808402Z", "updated_at": "2023-08-22T08:26:06.361047Z", "previously_billed_at": "2023-08-22T08:25:12.565118Z", "next_billed_at": "2023-09-22T08:25:12.565118Z", "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10887", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel" }, "discount": null }, "meta": { "request_id": "2a8303df-70ce-4c4f-911d-9faf08441a0d" }}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. |