Upgrade & Downgrade Subscriptions

You can upgrade or downgrade a customer’s subscription manually in your Paddle dashboard or by using our APIs to let your customers upgrade or downgrade in one click.

Upgrades / Downgrades billing behaviour

If the two plans you’re moving a subscription between have the same billing frequency (eg. both are monthly), the customer will retain the same billing dates. If the plans do not have the same billing frequency (eg. a customer is moving from monthly to yearly billing), the plan will be billed at a new interval immediately, starting on the date of the change. As an example: You switch a customer from one monthly plan to another, the billing date does not change. However, if you switch a customer from a monthly, to an annual plan, the customer is billed immediately, and the annual billing date will be recalculated from the day of the switch (date of plan switch + 1 year).

If the change moves a customer into a situation where a payment is required (for example moving a customer to a more expensive plan), Paddle will automatically attempt a payment of the amount that is owed.

When changing plans, Paddle will by default prorate the subscription costs. For example, if the customer is on a $10 monthly plan and is billed on the 1st of every month, you execute a plan change half way through the billing cycle (in this case, mid-month on a monthly cycle - eg. the 15th of the 30-day month). In this case, the customer has already paid $10 and used half of that (because they’re in the middle of the month). When the customer is switched to the new plan which has a price of $30.00:

  1. The unused portion of their current billing cycle is applied as a credit, in this case: $10 * (15 days used / 30 days total) = $5.
  2. The cost of the new plan for the remaining billing cycle (ie. the outstanding 15 days left in the month) is a debit of: $30 * (15 days remaining / 30 days total) = $15.
  3. The final prorated cost of switching from the Basic to the Pro plan is: +$5 credit - $15 debit = -$10 charge.

Depending on whether the customer is set to be billed immediately, they will either be charged $10 instantly, or this amount will be added onto their upcoming recurring payment amount.

If the customer is not billed immediately, the next billed amount would include the prorated charge with the payment required on the new plan for the upcoming month. Thus the next billed amount would be for a total of $40 ($30 for their upcoming billing interval, and $10 for the prorated amount from the plan change).

Since this example is a monthly-to-monthly plan change, it would not alter the billing date or cycle even if the customer is billed immediately.

Note: Proration calculation will not take any coupons or modifiers applied into account, nor are initial price overrides (prices) done via the Pay Link API.

When a subscription has been successfully upgraded or downgraded, this will trigger a Subscription Updated alert.

Upgrades / Downgrades via Dashboard

To manually upgrade or downgrade a customer’s subscription, go to your Paddle Dashboard > Customers > Subscribers. Here you can search for the specific subscription by the email, plan ID or subscription ID. Once you have found the subscription, click “View”, then select “Change Plan” under the Subscription section.

Please note that:

  • Subscribers on non-quantity plans can move to quantity plans but not the inverse.
  • Subscribers must be billed immediately when moving to a plan with a different billing interval.
  • Subscribers cannot be moved to a plan where the current currency is not enabled.
  • Subscribers cannot be moved to a different plan while on a trialing/paused/past due state.
  • Recurring coupons (if present) will be removed when the plan is changed.
Subscription options section
Subscription options section

When viewing a subscription on the dashboard, you can also choose to cancel or pause the subscription.

Upgrades / Downgrades via API

Allowing customers to upgrade or downgrade their subscription is an important part of subscription lifecycle management. With Paddle you can allow your self-serve customers to upgrade or downgrade in one click with our APIs.

In order to allow your customers to make subscription changes, we recommend that you create a customer/account management area on your website or app. Here you can display the current plan the customer is subscribed to and options for upgrading and downgrading.

Both upgrades and downgrades can be managed by calling the Update User API using the subscription_id. You can pass details such as whether or not to bill immediately, whether to prorate, and the plan_id the customer should be moved to.

curl -X POST -d 'vendor_id=1234567' \
             -d 'vendor_auth_code=1a54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'plan_id=678910' \
             -d 'bill_immediately=true' \
             -d 'prorate=true' \
https://vendors.paddle.com/api/2.0/subscription/users/update

For full details of the Update User API see our API documentation.