Change Subscription
A change to the customer's subscription is most often an upgrade or downgrade, but can also include changes to how the subscription is invoiced. Changes can be made immediately in the current billing cycle, at the customers next bill date, or when the subscription term renews.
Downgrades and upgrades are called subscription changes in Recurly. These can be a change in plan, quantity, price, or adding/removing add-ons. Subscription changes include additional updates, like a change in collection method or invoice notes. If you need to change the current billing cycle of a subscription, see our Postpone Subscription feature.
Feature Highlight: Only Bill What Changed
Recurly now only bills the difference in an immediate subscription change when the underlying plan has not changed. All Recurly sites created on or after June 30, 2017 UTC have this feature by default. Recurly sites created before that date will see the option to enable the feature at the bottom of the Invoice Settings page under Configuration in your Admin Console.
This page walks through Recurly's subscription change functionality assuming you have the Only Bill What Changes feature enabled.
If you still need to enable Only Bill What Changed, you can learn more about the Only Bill What Changed release here.
How to Change a Subscription
You can change a subscription via the Admin Console or the API. Recurly does not support subscription changes by your customer through the Hosted Pages.
In the Admin Console, find the Subscription Details page by going to the customer's account and clicking on the subscription's name. At the top right of the page, you will see a "Subscription Actions" dropdown where you can find the option to "Edit Subscription". On the Edit Subscription page, make your changes and click "Save Changes".
To understand all of the options available when you are changing a subscription, please read the documentation below.
Timing of Change
A subscription can be changed immediately, at the next bill date, or when the subscription term renews. Immediate changes will bill for the change right away. At next bill date changes will reflect the change on the customer's next bill. At term renewal changes will reflect the change on the first bill date of the renewal term. It is not currently possible to make an immediate change to a subscription but bill for that change at term renewal. Please contact Recurly Support if you would like to see this functionality added.
Most often, we see that merchants prefer to make upgrades immediately and downgrades at the next bill date or at term renewal. Immediate upgrades allow you to provide the customer with the higher value product and collect the additional money right away. At bill date and term renewal downgrades allow you to lock the customer into the agreed upon, and paid for, billing cycle, continuing to provide the customer with the higher value product until the next billing period or term begins.
When there are pending changes on a subscription already, you may select an option to change certain attributes of the subscription without impacting the other pending changes. When there are pending changes on a subscription that you do not wish to override, you can select the option to preserve pending changes and update the following values without any impacts to existing pending changes: shipping address, subscription terms, invoicing and payment, and custom fields.

Subscriptions can be cancelled at three different timeframes: immediately, next bill date, or term renewal.
Immediate Changes
Immediate subscription changes will bill for the difference in cost immediately. This means an invoice will be created and, if using automatic collection, a transaction will be attempted on the payment method provided in the Billing Information on the customer's account. If the transaction fails, the invoice and subscription will go into the Dunning process. If you would prefer to block immediate changes where the transaction fails or the account is past due, please see the Modification Enforcement section.
Invoice Preview
When you are making an immediate change to a subscription, and would like to see what the resulting invoices will be, click on the 'Preview Invoice' button before saving the changes. This will give you a snapshot of what invoices, both charge and credit, will be created for the customer, and will provide information on what the billable amount to the customer, based on the proration calculation, will be.
When 'Save Changes' is selected, the final amounts will be created and applied to the customer account. This amount may be slightly different than the amount seen on the preview invoice(s), since the final amount is calculated down to the exact second the change is made.

At Next Bill Date Changes
When a subscription change's timeframe is set to "next bill date", Recurly saves the changes so it can apply the changes when it next bills 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, the first request will be canceled. The second request will be applied at the timeframe indicated by the timeframe parameter. For "next bill date" change requests, there is no need to prorate the amounts. Recurly will adjust the subscription appropriately and then invoice the user at the new amount on the invoice.
If you want to update a pending change, please submit the original change plus the updated information. Pending changes can be cleared by updating the subscription Immediately with no other changes.
At next bill date change requests only apply to product changes. All other changes, like collection method and notes, will happen immediately, even if the change request is for the next bill date. These types of changes can be saved and applied at next bill date:
- Change the subscription's plan
- Change the plan fee price
- Change the plan fee quantity
- Add or remove an add-on
- Change an add-on price
- Change an add-on quantity
At Term Renewal Changes
When a subscription change's timeframe is set to "when term renews", 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 at the timeframe indicated by the timeframe parameter. For "At renewal" change requests, there is no need to prorate the amounts. Recurly will adjust the subscription appropriately and then invoice the user at the new amount on the renewal invoice.
If you want to update a pending change, please submit the original change plus the updated information. Pending changes can be cleared by updating the subscription Immediately with no other changes.
At renewal change requests only apply to product changes. All other changes, like collection method and notes, will happen immediately, even if the change request is for when the term renews. These types of changes can be saved and applied at renewal:
- Change the subscription's plan
- Change the plan fee price
- Change the plan fee quantity
- Add or remove an add-on
- Change an add-on price
- Change an add-on quantity
What Can Be Changed
Product changes can be applied immediately, at the next bill date, or when the term renews. Invoice-related changes will always apply immediately, even if at renewal is selected.
Can Be Changed Immediately
- Plan
- Plan/Add-on Price
- Plan/Add-on Quantity
- Add or Remove Add-on
- Collection Method
- Net-Terms
- PO Number
- Customer Notes
- Terms and Conditions
Can Be Changed At Bill Date and Term Renewal
- Plan
- Plan/Add-on Price
- Plan/Add-on Quantity
- Add or Remove Add-on
Changing a Subscription with 0 Renewals Remaining
In the case that a subscription has 0 renewals remaining, a pending subscription change will result in a renewal of the subscription. Because the subscription is about to expire, we interpret the request for a change to initiate a renewal. If you would like the subscription to expire, you can not send a change request and the subscription will expire at the end of the current term.
Making Changes to Canceled Subscriptions
A canceled subscription will always reactivate if an immediate change is submitted. If a change is made at next bill date or term renewal to a canceled subscription, the subscription will activate and create the pending change, which will apply at the requested timeframe.
Time-Based Proration
Immediate subscription changes will prorate charges and credits based on time down to the second. We use time-based proration because Recurly was initially founded on supporting digital subscription businesses where the cost represents time-based access to a service. If you require other forms of proration, please contact Recurly Support, so we can track your request.
Proration Formula
Proration is the time remaining in the current billing period divided by the time in the subscription's plan billing period. This is then multiplied by the per-unit price to get the correct amount to charge and credit.
We only charge for the remaining amount of time because the customer will be billed the full price when the subscription bills at the end of the current billing cycle, so we want to make sure we don't overcharge them and only charge for the actual time they will get to use the new product or service in this period. Similarly, we want to credit the customer what they paid for but will not use. Since they will not use the product or service for the remainder of the billing cycle, this is the portion that is returned as a credit.
(time remaining in current billing period / subscription's plan billing period) x (per unit price)
Or more specifically...
[(current billing period end date - time of change) / (plan billing period end date - plan billing period start date)] x (per unit price)
You probably notice that the denominator of the proration fraction refers to the plan billing period, not the subscription's billing period. This is because the billing cycle can be customized through the postpone feature. If the bill date is changed to be sooner or later, the numerator will reflect that new end date, but the denominator will respect the underlying plan's billing period end date. For example, if the subscription was for an annual plan, but after the subscription was created the current billing cycle end date was moved to an earlier date, the denominator would reflect a year while the numerator would reflect the new end date which would be less than a year out. Learn more about postponing subscriptions below.
Digital vs. Physical Products
Immediate subscription changes will prorate charges and credits based on time down to the second. This is common for digital services. Due to this time-based proration, we recommend that subscriptions with recurring physical goods only allow at next bill date and at term renewal changes.
Charges and Credits
In an immediate subscription change, if the plan has changed, credits will be created for the old version of the subscription and charges will be created for the new version of the subscription. We call this rebilling the subscription. If the plan has not changed, Recurly will look at each product in the change and create charges for what is new and credits for what was removed. We call this only billing what changed in the subscription. Below are examples of each type of change.
Subscription Changes
- Plan Change
- Quantity Change
- Price Change
- Change Quantity and Price
- Add or Remove Add-On
- Change Quantity-Based Add-On
- Change Usage-Based Add-On
- Terminate and Refund Subscription
- Change Plan Period
Plan Change
If the subscription's plan is changed, for example Silver to Gold, Recurly will rebill everything. Charges will be issued for the new version of the subscription, Gold, and credits will be issued for the old version of the subscription, Silver, that was paid for and will not be used.
If you are using add-ons with the same add-on code across different plans, Recurly will rebill the add-on when the plan changes for the subscription. This is due to the fact that Recurly does not know the add-ons are the same. While they have the same add-on code, their underlying id's are different.
Plan Change Example
Subscription is changed from Silver at $50/month with the Premium Support add-on at $20/month to Gold at $70/month, also with its own Premium Support add-on at $20/month.

Quantity Change
If a plan fee or add-on's quantity is increased or decreased, a charge or credit will be created for the quantity difference.
- For quantity increases, the charge quantity will reflect the additional quantity.
- For quantity decreases, the quantity will always be 1 and the price will reflect the removed quantity value.
Quantity Increase Example
A subscription to Gold with 5 users is increased to 7 users.

We get a charge with 2 x $5.00 by:
- 7 Qty - 5 Qty is 2 Qty
- Normal price is $10.00
- Proration is 50%
- Price prorated is $10.00 x 50% = $5.00
- 2 Qty x $5.00 Prorated Price = $10.00
Quantity Decrease Example
A subscription to Gold with 5 users is decreased to 3 users.

We get a credit with 1 x ($10.00) by:
- 5 Qty - 3 Qty is 2 Qty
- Normal price is $10.00
- Proration is 50%
- Price prorated is $10.00 x 50% = $5.00
- 2 Qty x $5.00 Prorated Price = $10.00
- Make it negative and you have ($10.00) as the credited price
Price Change
If a plan fee or add-on's price is increased or decreased, a charge or credit will be created for the price difference.
- For price increases, the charge quantity will match the current product's quantity in the subscription and the price will be the difference between the previous price and the new price, then multiplied by the proration percentage.
- For price decreases, the quantity will always be 1 and the price will reflect the price difference prorated and multiplied by the current quantity of the product in the subscription.
Price Increase Example
Subscription price is increased from $50/month to $70/month.

We get a charge with 1 x $10.00 by:
- Current Qty is 1
- $70.00 New Price - $50.00 Old Price = $20.00 price difference on the invoice
- Proration is 50%
- Price prorated is $20.00 x 50% = $10.00
- 1 Qty x $10.00 Prorated Price = $10.00
Price Decrease Example
Subscription price is decreased from $70/month to $50/month.

We get a credit with 1 x ($10.00) by:
- Current Qty is 1
- $50.00 New Price - $70.00 Old Price = ($20.00) price difference on the invoice
- Proration is 50%
- Price prorated is ($20.00) x 50% = ($10.00)
- 1 Qty x ($10.00) Prorated Price = ($10.00)
Change Quantity and Price
When both quantity and price are changed at the same time for a plan fee or add-on, that product will be rebilled and have both a credit and a charge.
Rebill Product Example
Subscription to Gold has 5 users at $10/month. Users are increased to 7 and the price is decreased to $8/month.

Add or Remove Add-On
If an add-on is added or removed, a charge or credit will be created for just that add-on that was changed.
Add-on Example
Subscription starts with the Emails add-on for $10/month, but then removes the Emails add-on and adds the Text Messaging add-on for $15/month.

Notice that the Gold plan fee is not shown on the change invoice because it didn't change. Similarly, if there was another add-on on the first invoice that did not change, it would also not show on the change invoice.
Change Quantity-Based Add-On
For any add-ons with Tiered, Volume, or Stairstep Pricing Models, all mid-cycle changes will be prorated accordingly. The invoices will display the charge/credit based on the subscription's tiers and prices.
In order to add additional units for the current billing period without proration, you can submit a one time charge immediately and a subscription change that takes effect at the next bill date.
Change Usage-Based Add-On
If an immediate change is not changing the subscription's plan, usage-based add-ons will create charges and credits in the following ways:
- If a usage-based add-on is not changed, it will not show up on the change invoice and any unbilled usage will remain unbilled
- If a usage-based add-on is removed, price changed, or percentage changed, it will create a charge for any current usage that hadn't been billed yet
- If a usage-based add-on is added and that is the only change, no invoice will be created for the immediate change, since usage-based add-ons do not show on their first invoice due to the fact that they bill in arrears
- If a usage-based add-on has unbilled corrections logged against a past cycle, those will not be invoiced in the immediate change unless the add-on is being changed. If the add-on is not being changed, the corrections will be invoiced at the next bill date.
Terminate and Refund Subscription
Recurly provides the option to refund a customer when terminating their subscription. This refund only refunds the last invoice of the subscription. The last invoice might be the most recent bill date, or an immediate change invoice from the current period. For merchants who allow immediate subscription changes, a refund due to a termination can be confusing because only the charges from the last subscription change are refunded, not the full period's charges. If the last invoice was for an immediate subscription change where the plan was not changed, the last invoice may not have all products for the subscription, only the last ones changed. Or the last invoice might have only had credits and is not refundable; therefore, the refund request is ignored.
Change Plan Period
Immediate subscription changes where the plan period stays the same (e.g. - monthly to monthly or yearly to yearly) will maintain the current billing period and current subscription term on the subscription and follow normal proration rules. If the immediate subscription change is a plan change where the underlying period changes (e.g. monthly to yearly or yearly to monthly) and/or the length of the term changes (e.g. 12 periods to 6 periods), the subscription billing term will start over and the new charges will not be prorated.
Example Change with Same Billing Period and Subscription Term
Customer subscribes to the Silver Plan, which is billed monthly with an annual term, on Jan 15, 2018 and then upgrades to the Gold plan, which is also billed monthly with an annual term, on May 15, 2018.
- Subscription will still have a current billing period of May 15 - June 15, 2018
- Change invoice will have a prorated charge for Gold with dates of May 15 - June 15, 2018
- Change invoice will have a prorated credit for Silver with dates of May 15 - June 15, 2018
- Remaining number of billing periods in the term is not affected
Example Change with Different Billing Period and Subscription Term
Customer subscribes to the Silver Plan, which is billed monthly with an annual term, on Jan 15, 2018 and then upgrades to the Gold Plan, which is billed quarterly with a two-year term, on May 15, 2018.
- Subscription will now have a current billing period of May 15, 2018 - Aug 15, 2018
- Change invoice will have a full charge for two-year Gold with dates of May 15, 2018 - Aug 15, 2018
- Change invoice will have a prorated credit for monthly Silver with dates of May 15 - June 15, 2018
Credits
A Credit's Original Charge
If you want to see which invoice has the charge line item from which a credit line item originated, you need to look at the credit's invoice itself to see the display we've added to help you and your customers.

Multiple Credits for One Product
A credit line item must always link back to one charge line item. This is important because any discounts or taxes reversed would be unclear in your reporting if there was one large credit linking to two or more charges. Due to the one-to-one credit-to-charge relationship, it is possible to get a subscription change invoice with two credits for the same product. Each credit line item will link back to a different charge line item on a different invoice. The invoice display will show the different invoices. See the example above of the invoice reference that will be visible on the invoice.
Multiple Credit Example
5 users of Gold at $10/user/month are purchased. Then 2 more users are added mid-cycle to bring the users up to 7. Then, with a quarter of the cycle left, 3 users are removed to bring the users down to 4.

In the last invoice, #3, we want to credit the customer for 3 users, which would be 3 x $10 = $30. Since only 25% of the cycle is left, we only want to give back 25% of $30, which is $7.50.
While the charge on invoice #2 has $10.00 that can be credited, the charge only represents 2 users and we are crediting 3, so we instead find the correct charges to credit before we apply proration. Since we want to credit $30 before proration, we need to find $30 worth of charges pre-proration. The charge on invoice #2 is $20 before proration. The charge on invoice #1 is $50, and was never prorated. Since we work our way back, we need the full charge on invoice #2 and only $10 of the charge on invoice #1.
- Credit remaining for Gold (from invoice #2): 1 x ($20)
- Credit remaining for Gold (from invoice #1): 1 x ($10)
Then we prorate by 25% to get:
- Credit remaining for Gold (from invoice #2): 1 x ($5)
- Credit remaining for Gold (from invoice #1): 1 x ($2.50)
For a total credit of ($7.50)
Credit Quantity Is 1
Credits created in a subscription change event will always have a quantity of "1". Custom credits and refunds can still have a non-one quantity.
Customers of Recurly have the flexibility to change the price and quantity of a subscription. When you consider more complex combinations of changes in a single billing period, you can end up with two credits for the same product that have quantities and prices that are not clear. Instead of having special rules for a credit's quantity and price depending on the type of change, that you might then have to explain to your customers, we decided it would be less confusing to explain that quantity is always 1 on the invoice and have your customers focus instead on the amount credited. Their subscription will always reflect the current quantity and price, confirming any product changes the customer made.
Why Quantity is 1 Example
5 users of Gold at $10/user/month are purchased. Then 2 more users are added a quarter into the cycle to bring the users up to 7. At mid-cycle, the price per user is raised from $10 to $15. Then, with a quarter of the cycle left, 3 users are removed to bring the users back down to 4, still at $15/user.

Invoice #4A shows what the invoice would look like if we did not force quantity to 1. The removal of 3 users is showing a credit with quantity of 7 and a credit with quantity of 2, which have nothing to do with 3 users. Invoice #4B shows the credit quantity forced to 1, to direct the customer's attention to the amounts being credited from the two past invoices for Gold in the billing cycle.
To dig into the details, we know we want to credit 3 users at $15/user, or $45. But with only 25% left in the cycle, we really want to credit only 25% x $45, which is $11.25.
We start by grabbing needed charges pre-proration, so we need $45 worth of charges. The charge on invoice #3 is $35 pre-proration. That leaves $10 needed from the charge on invoice #2, which has a total of $20 pre-proration.
From invoice #3 we can grab the "7 x $5.00" charge and prorate the price by 25% to "7 x $1.25".
Then from invoice #2 we can grab the "2 x $10.00" charge, but we only need $10.00 pre-proration, so do we reduce the price to $5.00 before prorating or do we reduce the quantity to 1? In this case we left quantity at 2 and cut the price in half before prorating by 25% to get "2 x $1.25".
As you can see with referencing a portion of the charge on invoice #2, it is debatable whether the charge should be cut by quantity or price, and changing method for a product price change vs. a product quantity change can lead to confusing rules for your customers. Due to this, we opted to force quantity to 1 on credits like the result in invoice #4B.
Taxes on Credits
Credits issued in an immediate subscription change will always reverse any taxes collected on the referenced charge. Note that the tax amount reversed will be the portion related to the credited amount. If you enable tax collection for the first time, existing subscribers that change their subscription in the middle of a billing period may see new charges with tax and credits with no tax reversal.
Different Tax Rates
If you allow quantity, add-on, or price changes where the subscription's plan is not changed, there could be credits on a change invoice from different charge invoices. This means it could be possible to have different tax rates and addresses affecting the tax reversals on the credits. For example, a customer may have moved between subscription changes and one credit links back to the old address and another credit links back to the new address. Recurly will calculate the tax reversal on the credit using the correct original address, even though the invoice itself will show the current address of the customer.
In the event of mixed tax rates on the invoice, Recurly will display the tax rate at the line item level and the invoice level display will only say "Taxes". Here is an example of a customer that started in Australia, then moved to Israel and upgraded, and then finally downgraded creating two credits with different tax rates.

Discounts
Discounts on immediate subscription change invoices follow two primary rules:
- Credits will reverse any discounts on the referenced charges.
- Charges will only be discounted by currently active coupon redemptions.
Credit Discounts
When discounts are reversed on a credit, Recurly will smooth the discounts in the proportion of the credit to the charge it is against.
Percentage Example:
Given a subscription with quantity 10, $1 per quantity and a 20% off forever coupon. The first invoice will be for $8 ($10 - $2 discount). A downgrade of quantity 3 will result in a credit for $3 and $0.60 discount, so ($2.40) after the discount reversal. The discount of $0.60 comes from $3/$10 x $2.
Fixed Amount Example:
Given a subscription with quantity 10, $1 per quantity and a $2 off forever coupon. The first invoice will be for $8 ($10 - $2 discount). A downgrade of quantity 3 will result in a credit for $3 and $0.60 discount, so ($2.40). The discount of $0.60 comes from $3/$10 x $2.
Charge Discounts
When active coupon redemptions are applied to new charges, Recurly will prorate any fixed amount discounts following the same proration rate of the charge. Recurly prorates fixed amount discounts in an immediate subscription change because the discount represents the time of the cycle. If the customer is 50% through their cycle and only going to be charged 50% of the plan price, we want to ensure that they only get 50% of the discount amount. Percentage discounts automatically represent a prorated portion because they are a percentage of an already prorated amount.
It is not possible to have a fixed amount coupon redemption not prorate when applied in an immediate change. If you require this use case, please look at custom credits as an alternative and write in to Recurly Support to tell us this is something you would like us to support.
Single-Use Coupons
Single-use coupons only discount charges on one invoice. If a single-use coupon is used on a bill date invoice, it will not discount new charges on an immediate change invoice.
For example, if your single-use coupon is for "all plans" and is used on the purchase of the Silver plan, but then the customer upgrades to Gold mid-cycle, the Gold charge will not be discounted and a portion of the single-use discount will be reversed on the credit for Silver. The customer ends up losing a portion of the discount they previously received.
If it is important that the customer never lose the discount due to immediate changes, you should use limited time or forever duration coupons, not single-use.
Fixed Amount and Long Duration Coupons
Recurly's fixed-amount coupons that have a limited time or forever duration are meant to be a fixed amount off for the billing period. This is why we prorate fixed amount discounts in an immediate subscription change event. Recurly tracks what discount amount is remaining for a coupon redemption for the subscription's billing period. For example, if a $50 off coupon redemption is completely used on a bill date invoice, we will make sure no more of the discount is applied in an immediate change, even if the type of product in the change is eligible and the coupon redemption is still active.
Recurly's discounting does allow a remaining amount to be applied later in the billing period if it is not consumed on the bill date. This is more of an edge case. For example, if only $40 of the $50 discount is used on the bill date, we will track that a $10 discount amount is still available in the billing period. But since the $50 is per period, we will prorate the $10 if applied in an upgrade to reflect that time has passed.
Mid-Cycle Redemptions and Upgrade Discounts
Discounts will affect immediate changes differently if the subscription is being rebilled due to a plan change or only billing what changed due to a quantity, price, or add-on change.
If you redeem a new coupon on an account in the middle of the customer's subscription billing period and an immediate change rebills the subscription, the discount will apply to the new version of the subscription for the time remaining in the period.
If instead the immediate change only bills what changed, the discount will apply to only the additional quantities, price, or add-ons. For example, if quantity is increased from 7 to 10, the new charge is for 3 quantities and will therefore only discount the additional 3 quantities, instead of the full 10. Conceptually, if you are going to give someone a discount for upgrading, you are giving them the discount on just the upgraded portion, since they committed to the upgrade mid-cycle. At the bill date, the discount would have the ability to apply to all 10 quantities.
Free Trials
No Change Invoices
While an invoice is created when a subscription starts its free trial, Recurly will not create an invoice for an immediate change during a trial period. This means Recurly will not charge a customer for an upgrade while they are in trial. The customer is essentially trialing anything you allow them to have. If you would like to charge the customer for a subscription change while in trial, you will need to create a one-off invoice for the charge.
Trials and Plan Changes
If a subscription change changes the underlying plan and the new plan has a different trial rule, the original plan's trial rules will hold.
Example: 7-Day Trial to No Trial
If a subscription currently in a 7-day trial changes its plan to one without a trial, the subscription will stay in the current 7-day trial, but now have access to the new plan. For example, if the customer is 4 days into the trial and changes their plan, they will get the new plan free for 3 days.
Example: No Trial to 7-Day Trial
If a subscription is currently not in a trial and changes its plan to one with a 7-day trial, the subscription will not receive a trial and will be charged for the new plan.
Example: 7-Day Trial to 14-Day Trial
if a subscription currently in a 7-day trial changes its plan to one with a 14-day trial, the subscription will stay in the current 7-day trial, but now with access to the new plan. For example, if the customer is 4 days into the trial and changes their plan, they will only get a 3-day trial of the new plan that normally has a 14-day trial.
Convert Trial
If you do not want the original trial to continue, you can submit a request to the Convert Trial API or use the Admin Console. This request will end the trial and transition the subscription to a new billing cycle on the new plan immediately. If the transaction is not successful, the trial will continue.
Coupon Redemption
Coupons can only be redeemed in subscription changes that are immediate and include a product change.
Coupon redemption was added to subscription changes to support upgrades with subscription-level coupons. Since a subscription-level coupon must be tied to a subscription with an eligible plan at the time of redemption, upgrades present a scenario where the account does not necessarily have a subscription to the coupon's eligible plans. Therefore, redeeming the subscription-level coupon while the subscription's plan is changing to an eligible plan solves that problem.
While coupon redemption was added to subscription changes for subscription-level coupons, account-level coupons can be redeemed as well. Note that the subscription's new version has to have a plan that is eligible for the new coupon.
Recurly does not allow coupons to be redeemed in at renewal requests because the coupon may have redemption limits for the campaign or the account and managing pending redemptions or immediate redemptions related to pending changes that might be canceled could lead to a poor user experience.
Coupon redemption requires a product change to avoid a subscription being change only for the sake of redeeming a coupon. Coupons can always be redeemed directly on the account, outside of a subscription action. A product change includes a plan, price, quantity, or add-on change.
Email Communications
Both automatic and manually collected subscriptions will issue the Subscription Change email, if enabled, to the customer at the time of the change. This means an immediate change will issue the email immediately and an at renewal change will issue the email when the subscription renews
- Manually collected subscriptions will additionally send the New Invoice email, if enabled, to the customer.
- Automatically collected subscriptions will additionally send either the Payment Confirmation or Payment Declined email, if enabled, to the customer, depending on whether the transaction was successful or declined. If the immediate change was a downgrade, no "Payment" email will go out.
note: If Credit Invoices is enabled, the Subscription Change email will be sent immediately regardless of the time of change.
Modification Enforcement
Some merchants may prefer to have their customers current and up-to-date on all payments before allowing a subscription upgrade or downgrade. Recurly allows this to be configured on your Invoice Settings page through two different options:
Require paid invoice and successful transaction on upgrades
When upgrading an existing subscription immediately, require that the account have no past due invoices and the payment information on file process successfully in order to complete the upgrade. If the payment information is declined, the subscription will be kept on the original plan.
Require paid invoice to downgrade
When downgrading an existing subscription immediately, require that all invoices have been successfully paid in order to complete the downgrade. If any invoice is past due, the subscription will be kept on the original plan, and an error will be provided to the customer; "Your account is currently past due, please update your billing information before changing your subscription."
Learn more about subscription modification enforcement.
Site Plan Changes and Existing Subscribers
If a subscription's underlying plan is edited at the site level, the changes will only impact new subscribers—your current subscribers remain as-is at the plan terms they agreed to at the time of subscription signup. You cannot edit the billing period of a plan after it is created, to avoid existing subscriptions billing with the new period on their next invoice. We recommend creating a new plan if you wish to do this.
Updated 9 months ago