Upgrade or downgrade

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

Get existing items

If you're working with the API, you'll need to get 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.

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

Response

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01gvne45dvdhg5gdxrz6hh511r",
4    "status": "active",
5    "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd",
6    "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-03-16T14:45:30.683934Z",
10    "updated_at": "2023-03-16T14:45:30.683934Z",
11    "started_at": "2023-03-16T14:45:30.683929Z",
12    "first_billed_at": "2023-03-16T14:45:30.683929Z",
13    "next_billed_at": "2023-04-16T14:45:30.683929Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "manual",
17    "billing_details": {
18      "enable_checkout": false,
19      "purchase_order_number": "",
20      "additional_information": "",

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.

1
2
3
4
5
6
7
8
9
1{
2  "proration_billing_mode": "prorated_immediately",
3  "items": [
4    {
5      "price_id": "pri_01gvne87kv8vbqa9jkfbmgtsed",
6      "quantity": 1
7    }
8  ]
9}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01gvne45dvdhg5gdxrz6hh511r",
4    "status": "active",
5    "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd",
6    "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-03-16T14:45:30.683934Z",
10    "updated_at": "2023-03-16T14:45:30.683934Z",
11    "started_at": "2023-03-16T14:45:30.683929Z",
12    "first_billed_at": "2023-03-16T14:45:30.683929Z",
13    "next_billed_at": "2023-04-16T14:45:30.683929Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "manual",
17    "billing_details": {
18      "enable_checkout": false,
19      "purchase_order_number": "",
20      "additional_information": "",

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.

1
2
3
4
5
6
7
8
9
1{
2  "proration_billing_mode": "prorated_immediately",
3  "items": [
4    {
5      "price_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
6      "quantity": 1
7    }
8  ]
9}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01gvne45dvdhg5gdxrz6hh511r",
4    "status": "active",
5    "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd",
6    "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-03-16T14:45:30.683934Z",
10    "updated_at": "2023-03-16T14:45:30.683934Z",
11    "started_at": "2023-03-16T14:45:30.683929Z",
12    "first_billed_at": "2023-03-16T14:45:30.683929Z",
13    "next_billed_at": "2023-04-16T14:45:30.683929Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "manual",
17    "billing_details": {
18      "enable_checkout": false,
19      "purchase_order_number": "",
20      "additional_information": "",

Events