Upgrades & Downgrades

Recurly allows your subscribers to easily move between subscription plans, upgrade or downgrade the quantity, and adjust the unit amount. We also let you control when the change occurs: immediately or at the end of the current billing cycle.

If a subscription change occurs at renewal, there is no need to prorate the amounts. Recurly will adjust the subscription appropriately and then invoice the user at the new amount.

For changes that occur immediately, Recurly will:

If the charge is greater than the credit (plus the user’s current balance), the user will be charged the difference. If the credit is greater than the charge, then the user will have a credit on their account that will be applied to their next renewal charge.


Typically in an upgrade scenario, a subscriber is moving to a more expensive plan and you would like to receive the money immediately. In this scenario, you would send a change subscription request to Recurly and specify that the timeframe is now. Recurly will perform the necessary prorations to upgrade the subscriber immediately. For more information, see the Subscriptions API.


As an example, let’s say the user is on a $10/mo. plan and moves to a $20/mo. subscription halfway through the month. Recurly will create a $5 credit for the current subscription and a $10 charge for the new subscription, thus billing the user $5 for the upgrade. When the subscription renews at the end of the month, it will renew at $20.


Downgrade requests typically occur at the end of the current billing cycle. When a subscriber wants to move to a cheaper plan, they have already committed to the more expensive plan for a given duration and you have already collected the funds for that period. To process a downgrade with Recurly, submit a change subscription request and set the timeframe to renewal. Recurly will downgrade the subscription when it renews. For more information, see the Subscriptions API.

Changing Plans

If you offer a monthly and yearly subscription, your users will want to be able to change their billing frequency between the two. These changes are neither upgrade or downgrades. Under ordinary circumstances, the billing cycle adjustment should occur when the current subscription renews. For these adjustments, we recommend setting the timeframe to renewal.


If a subscriber is on a monthly plan and is halfway through the month before deciding to switch to the yearly plan, then the switch should happen at the end of the month. In this scenario, you would submit a change subscription request with a timeframe of renewal. When Recurly renews the subscription at the end of the month, it will switch the subscription to the yearly plan and charge the full year’s price. This keeps your transaction dollar amounts even and avoids proration.

Pending Changes

When a subscription change’s timeframe is set to renewal, Recurly saves the changes so it can apply the changes when it’s time to renew the subscription. Recurly only persists one change request. If you submit a change request to apply at renewal and then submit a second change request before renewal, the first request will be canceled. The second request will be applied immediately or at renewal, as indicated by the timeframe parameter.

If you want to update a pending change, please submit the original change plus the updated information. Today, the only parameters are: subscription plan, quantity, and unit amount.