The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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 or at the next renewal.

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.

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

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.

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 when you are changing a subscription, please read the documentation below.

Timing of Change

A subscription can be changed immediately or at the next term renewal. Immediate changes will bill the change right away. At term renewal changes will reflect the change on the first bill date invoice of the renewal term. It is not currently possible to make an immediate change to the subscription, but bill 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 immediate and downgrades at renewal. Immediate upgrades allow you provide the customer the higher value product and collect the additional money right away. At 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 renewal.

Change a Subscription with 0 Renewals Remaining

In the case that a subscription has 0 renewals remaining, a pending subscription change will not be applied. Because the subscription is set to expire at the end of the current term, any pending changes will be lost when the subscription is expired.

In order to apply a pending change to a subscription with 0 renewals remaining, you will first need to extend the renewals on the subscription. To do this go to Options->Edit Subscription. Go down to the Timing section and select Renew Forever or enter a value greater than 1 into the Limited Billing Cycle field. Select Immediate for Plan Effective Date and Save Changes. This will effectively extend the billing cycles for your plan, so that a pending subscription change can now be saved.

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

Making Changes to Canceled Subscriptions

A canceled subscription will always reactivate if an immediate change is submitted. If an at renewal change is made to a canceled subscription, the subscription will activate and create the pending change, which will apply at next bill date.

What Can Be Changed

Product changes can be applied immediately or at renewal. 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 Term Renewal

  • Plan
  • Plan/Add-on Price
  • Plan/Add-on Quantity
  • Add or Remove Add-on

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.

Table of Contents

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 over charge 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 period) x (per unit price)

Or more specifically...

[(current billing period end date - time of change) / (plan period end date - plan period start date)] x (per unit price)

You probably notice that the denominator of the proration fraction refers to the plan 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 period's 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 in to a shorter 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 the postponing subscriptions below.

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.

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)

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

A Credit's Original Charge

Today we don't show you which charge line item the credit line item is from. For example in the Line Items export we don't provide the id of the charge the credit was against. Later this year, in 2018, we will be revealing the link in the exports and API. For now, if you want to see which invoice has the charge line item the credit line item is from, 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 back 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.

Usage-Based Add-ons

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

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.

Later this year we are going to revamp the refund in a terminate action to actually refund all charges issued in the cycle, not just the last invoice. Stay tuned for this change towards the end of 2018.

Plan Period Changes

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 (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 an annual term billed monthly on Jan 15, 2018 and then upgrades to the Annual billed Monthly Gold plan on May 15, 2018.

  • Subscription will still have a current billing cycle of May 15 - June 15, 2016
  • 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, 2016
  • 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 an annual term billed monthly on Jan 15, 2018 and then upgrades to the Gold Plan which is a two year term billed quarterly on May 15, 2018.

  • Subscription will now have a billing cycle of May 15, 2016 - 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

Discounts

Discounts on immediate subscription change invoices follow two primary rules:

  1. Credits will reverse any discounts on the referenced charges.
  2. 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 charge 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 use 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. This is true for both immediate and at renewal changes.

Example: 7-Day Trial to No Trial
If a subscription currently in a 7-day trial changes it's 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.

If you do not want to original trial to continue, you can:

  • Submit the change as an at renewal request and then force the subscription to renew in the next hour using the Postpone API call or Change Renewal Date in the Admin Console. This will end the trial and transition the subscription to a new billing cycle on the new plan.
  • Or you terminate the current subscription and start a new subscription to the new plan without a trial.

Example: No Trial to 7-Day Trial
If a subscription is currently not in a trial and changes it's 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 it's 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.

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 immediately or at renewal, as 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

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 Grandfathering

If a subscription's underlying plan is edited at the site level, the changes will only impact new subscribers—your current subscribers remain grandfathered in at the plan terms they agreed to at 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.

Only Bill What Changed Release

On June 30, 2017 UTC (June 29, 2017 PT), Recurly released the Only Bill What Changed feature. This feature is on all new Recurly sites by default and can be enabled on pre-existing sites on the Invoice Settings page under Configuration in the Admin Console.

Note that if existing customers create a new Recurly site after June 30, 2017, the Only Bill What Changed feature will be enabled on the new site by default, even if the existing site does not have the feature enabled.

Important Feature Call-outs

  • Once Only Bill What Changed is enabled, it cannot be disabled
  • All Recurly sites will be required to enable Only Bill What Changed in 2018
  • Once enabled, existing subscriptions where the last invoice was an immediate change invoice will still rebill everything if the next invoice is also an immediate change. The following invoices will only bill what changed. Learn more
  • Any immediate change where the plan is changed will still rebill everything, even if there is an add-on with the same add-on code across plans. Learn more
  • Quantity changes will create a charge or credit for the quantity difference. Learn more
  • Price changes will create a charge or credit for the price difference. Learn more
  • Changing quantity and price for a single product will rebill the product. Learn more
  • Any decrease requiring a credit will create a credit with a quantity of 1. Learn more
  • A credit's original charge won't necessarily be on the last invoice of the subscription anymore. Learn more
  • There may now be two credits for the same product on the change invoice. Learn more
  • Single use discounts will now not be reversed in an upgrade where we only bill what changed.
  • Mid-cycle coupon redemptions will now apply to only the difference of an upgrade that only bills what changed instead of the full new version of the subscription. Learn more

How To Enable Only Bill What Changed

If your Recurly site was created before June 30, 2017, you will see an option called "Only Bill What Changed" at the bottom of the Invoice Settings page under the Configuration section. Click the "Enable" button to turn on Only Bill What Changed.

Only Bill What Changed Cannot Be Disabled

Once you enable the Only Bill What Changed feature, it cannot be disabled. Please review our documentation before enabling the feature. All Recurly sites will be required to enable Only Bill What Changed in 2018.

Option to enable Only Bill What Changed

Option to enable Only Bill What Changed

After Only Bill What Changed is enabled

After Only Bill What Changed is enabled

Existing Subscriptions

Some subscriptions currently in a billing period when the feature is added will still rebill everything in their next immediate change, but all immediate changes after the initial one will start only billing what changed. This is required because we need to fill new database tables with data about the subscription cycle before we can correctly bill only what changed.

What Subscriptions Will Rebill On The Next Invoice?

If an existing subscription's last invoice, prior to the Only Bill What Changed feature being enabled, was a renewal invoice, Recurly will only bill what changed in any immediate change that comes through.

If the existing subscription's last invoice, prior to the Only Bill What Changed feature being enabled, was an immediate subscription change invoice, Recurly needs an invoicing event in the old format before it can only bill what changed moving forward.

  • If the next invoice is a renewal, then any following immediate change will only bill what changed.
  • If the next invoice is an immediate change, the fact that the last invoice was also an immediate change will require Recurly to rebill everything following the old change logic. Any immediate change after that will only bill what changed.

How Do I Identify Subscriptions That Will Rebill On The Next Invoice?

Once Only Bill What Changed is enabled on your Recurly site, you can tell if a subscription will rebill everything in the next immediate change by looking at the Subscription Details page or the Edit Subscription page. You will see this yellow alert banner:

As soon as the existing subscription has an invoicing event, the yellow banner will disappear and the subscription will only bill what changed on any future invoices. If your subscriptions are all monthly, a month after enabling the feature all subscriptions will be able to bill only what changed. If your subscriptions are yearly, you may have some existing subscriptions in this scenario for up to a year. All new subscriptions created after you enable Only Bill What Changed will not have this banner and will always only bill what changed.