Paddle Billing
Search

Upgrade or downgrade

Upgrade or downgrade subscriptions by replacing items on a subscription.

Depending on your billing model, you might let your 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

You can't make changes to a subscription if the next billing period is within 30 minutes.

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

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'd like 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.

Change base plan

Change the base plan when your customers want to move from one plan to another. For example, from Pro to Enterprise.

You can choose any proration billing mode.

Build a request that includes an array of price IDs. Remove the price ID for the existing base plan, then add:

  • Existing items that you'd like to keep on the subscription, like any addons.
  • The price ID for the new base plan.

Send a PATCH request to the /subscriptions/{subscription_id} endpoint that includes the new items array.

Request

In the request:

  • Include proration_billing_mode to tell Paddle how to handle billing for changes.
  • items should include a price_id and quantity for each item.
  • New items must include a quantity.
  • You may omit quantity for existing items if you're not making changes.
  • Optionally include on_payment_failure to tell Paddle how to handle this change if payment fails.

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.

Change billing frequency

Change the billing frequency when your 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 you sell 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 only use prorated_immediately and full_immediately when changing billing frequency. If you choose full_immediately, no proration happens.

Build a request that includes an array of price IDs. Remove the price ID for the existing base plan and any recurring addons, then add:

  • Existing items that you'd like to keep on the subscription, like one-time charges.
  • The price ID for the new base plan.
  • The price IDs for any new addons.

Send a PATCH request to the /subscriptions/{subscription_id} endpoint that includes the new items array.

Request

In the request:

  • Include proration_billing_mode to tell Paddle how to handle billing for changes.
  • items should include a price_id and quantity for each item.
  • New items must include a quantity.
  • You may omit quantity for existing items if you're not making changes.
  • Optionally include on_payment_failure to tell Paddle how to handle this change if payment fails.

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.

Notifications

subscription.updatedOccurs when you update items on a subscription.
transaction.createdOccurs when you choose a proration billing mode that bills the customer for changes.