Depending on your billing model, you might let customers upgrade or downgrade their plan. This could mean:
- Customers want to change their base plan, for example going from Pro to Enterprise
- Customers want to change their billing frequency, for example going from monthly to annual
Add items for new users, modules, or other addons
Adding or removing users, modules, one-off fees, or other addons typically involves adding or removing items. For example, you might offer a module called "Advanced Reporting" across all plans. To learn more, see Add or remove items
How it works
In Paddle, there's no rigid hierarchy of products. This means there's no formal distinction between products that you consider base plans and products that you consider addons.
When customers upgrade or downgrade, they're technically replacing items on their subscription. For example, if a customer moves from Pro to Enterprise, you'd remove the Pro product and replace it with the Enterprise one. You can do this in one API call, or on one screen in the Paddle dashboard.
Customers might also say that they're upgrading or downgrading when they change their billing frequency. For example, a customer might say that they'd like to "upgrade to the annual plan." In this case, you'd swap all monthly prices for annual prices.
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.
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.
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 upgrade or downgrade 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 active to get a list of active subscriptions.
Change base plan
Change the base plan when customers want to move from one plan to another. For example, from Pro to Enterprise.
You can choose any proration billing mode.
- Go to Paddle > Customers, and find the customer whose subscription you want to change.
- Find the subscription under the Subscriptions heading and click it.
- From the subscription overview page, choose Edit subscription
- Make changes to the items list.
- To prorate charges, toggle Charge for what's remaining of the current billing period? on, then choose how you want to handle proration.
- Click Continue to review, then Save to proceed.
Change the base plan 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 upgrade or downgrade. - 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, build an items array. Remove the price ID for the existing base plan, then add existing items that you want to keep, plus the price ID for the new base plan.
Include proration_billing_mode to tell Paddle how to bill for the change. 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).
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. You should present this to customers if you offer an in-app workflow to upgrade or downgrade.
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_immediately", "items": [ { "price_id": "pri_01gvne87kv8vbqa9jkfbmgtsed", "quantity": 1 } ]}{ "data": { "id": "sub_01gvne45dvdhg5gdxrz6hh511r", "status": "active", "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd", "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg", "business_id": null, "currency_code": "USD", "created_at": "2023-03-16T14:45:30.683934Z", "updated_at": "2023-03-16T14:45:30.683934Z", "started_at": "2023-03-16T14:45:30.683929Z", "first_billed_at": "2023-03-16T14:45:30.683929Z", "next_billed_at": "2023-04-16T14:45:30.683929Z", "paused_at": null, "canceled_at": null, "collection_mode": "manual", "billing_details": { "enable_checkout": false, "purchase_order_number": "", "additional_information": "", "payment_terms": { "frequency": 2, "interval": "week" } }, "current_billing_period": { "starts_at": "2023-03-16T14:45:30.683929Z", "ends_at": "2023-04-16T14:45:30.683929Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "recurring_transaction_details": null, "next_transaction": null, "scheduled_change": null, "items": [ { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-03-16T14:48:08.122643Z", "updated_at": "2023-03-16T14:48:08.122643Z", "previously_billed_at": null, "next_billed_at": "2023-04-16T14:45:30.683929Z", "price": { "id": "pri_01gvne87kv8vbqa9jkfbmgtsed", "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540", "description": "Monthly", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "5000", "currency_code": "USD" } } } ], "custom_data": {}, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/cancel" } }, "meta": { "request_id": "3fbb2766-5f14-4039-bff8-30cfc9ac0722" }}Change billing frequency
Change the billing frequency when customers want to change from paying in one interval to another. For example, from monthly to annually.
When you change billing frequency, you may need to replace multiple items — including addons — so they all have the same frequency. For example, if customers can purchase a Premium Support addon for $200 a month, replace this with a price for Premium Support that bills yearly when moving to an annual base plan.
You can use prorated_immediately, full_immediately, and do_not_bill when changing billing frequency.
- Go to Paddle > Customers, and find the customer whose subscription you want to change.
- Find the subscription under the Subscriptions heading and click it.
- From the subscription overview page, choose Edit subscription
- Make changes to the items list.
- To prorate charges, toggle Charge for what's remaining of the current billing period? on, then choose how you want to handle proration.
- Click Continue to review, then Save to proceed.
Change billing frequency 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 upgrade or downgrade. - 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, build an items array. Remove the price ID for the existing base plan and any recurring addons, then add existing items that you want to keep (like one-time charges), plus the price ID for the new base plan and any new addons.
Include proration_billing_mode to tell Paddle how to bill for the change. Only prorated_immediately, full_immediately, and do_not_bill are allowed when changing billing frequency. Optionally, include on_payment_failure to control payment failure behavior (defaults to prevent_change).
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. You should present this to customers if you offer an in-app workflow to upgrade or downgrade.
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_immediately", "items": [ { "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea", "quantity": 1 } ]}{ "data": { "id": "sub_01gvne45dvdhg5gdxrz6hh511r", "status": "active", "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd", "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg", "business_id": null, "currency_code": "USD", "created_at": "2023-03-16T14:45:30.683934Z", "updated_at": "2023-03-16T14:45:30.683934Z", "started_at": "2023-03-16T14:45:30.683929Z", "first_billed_at": "2023-03-16T14:45:30.683929Z", "next_billed_at": "2024-03-16T14:45:30.683929Z", "paused_at": null, "canceled_at": null, "collection_mode": "manual", "billing_details": { "enable_checkout": false, "purchase_order_number": "", "additional_information": "", "payment_terms": { "frequency": 2, "interval": "week" } }, "current_billing_period": { "starts_at": "2023-03-16T14:45:30.683929Z", "ends_at": "2024-03-16T14:45:30.683929Z" }, "billing_cycle": { "frequency": 1, "interval": "year" }, "recurring_transaction_details": null, "next_transaction": null, "scheduled_change": null, "items": [ { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-03-16T14:48:08.122643Z", "updated_at": "2023-03-16T14:48:08.122643Z", "previously_billed_at": null, "next_billed_at": "2024-03-16T14:45:30.683929Z", "price": { "id": "pri_01gsz91wy9k1yn7kx82aafwvea", "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540", "description": "Annual", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "year" }, "trial_period": null, "unit_price": { "amount": "50000", "currency_code": "USD" } } } ], "custom_data": {}, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/cancel" } }, "meta": { "request_id": "3fbb2766-5f14-4039-bff8-30cfc9ac0722" }}Events
subscription.updated | Occurs when you update items on a subscription. |
transaction.created | Occurs when you choose a proration billing mode that bills the customer for changes. |