Feature Overview

This feature allows billing periods to be set independently of plan length. By decoupling these two aspects, you can create plans that have a single subscription term with multiple billing periods, such as an annual subscription that is billed quarterly. You will have the option to create billing commitments for your customers that can require your subscribers to complete their commitment and pay for the remainder of the term. You’ll also be able to offer longer initial commitments that convert to shorter commitments (e.g one year commitment that converts to a monthly commitment after one year).

Sample Business Models Supported
Examples:

• B2B SaaS business that wants to create a 2 year contract that bills the customer quarterly
• B2C media streaming business that wants to promote a new channel at a discounted price, if a customer signs up for a year commitment.
• B2B subscription businesses now have the ability to create and configure subscriptions that map to a contractual commitment.
• B2C subscription businesses have the ability to offer payment plans or promotional incentives based on an initial commitment to their product.

These feature enhancements are available in the Admin UI and the API.

Billing Structure for Plans

Subscription terms feature adds more enhancements to the billing configuration when creating a plan.

• Subscription Term: the default commitment length for subscriptions to this plan, unless overwritten when creating or editing the subscription. A term can be comprised of 1 or multiple billing periods.
• End of Term Behavior: this determines whether the subscription will automatically renew for another term or expire at the end of the current term.

Billing Period and Price per Billing Period

When creating a plan you will need to specify the billing period for when a customer should be charged. Once a plan is created, you cannot edit the billing period as this would impact the term length of existing subscriptions (e.g if you changed a monthly billing period to quarterly). We recommend creating a new plan if you want a different plan billing period.

Subscription Billing Term Length

A subscription's length will be determined by the subscription term, which is the number of billing periods that a customer will be committed to for a subscription.

A subscription will always default to the plan's term configuration unless overwritten when adding or editing the subscription.

📘

Month to Month Subscriptions

If your business is structured predominantly with plans that are monthly and auto-renewing, you will want to create plans that have a monthly billing period and a term length of 1 billing period.

End of Billing Term Behavior

When creating your plan, you need to define the renewal behavior when a subscription term completes. If you’d like subscriptions to automatically renew for another term after a current term completes, you should configure the plan to Auto-Renew. Or, if you want the subscription to expire after completing the subscription term you should configure the plan to Expire.

Based on your business, you may configure your plans to auto renew term or you may want them to expire. For example, if you are a B2C streaming media business, you'll want to configure plans to "auto renew term", so that your subscribers do not churn at the end of a subscription term. Or perhaps if you are an IOT business that wants to set up "payment plans" for a your physical device that you are selling, you would want to set up the plan to Expire once the subscription term (i.e payment installments) is completed.

Example Plan Types
The subscription terms feature allows for a lot of flexibility when configuring a plan. Below are a few examples of the billing structures you can utilize:

• Month to Month Subscription
• Billing Period = 1 month
• Subscription Term = 1 billing period
• Auto-Renew Term
• 6 Month Auto-Renewing Subscription
• Billing Period = 6 months
• Subscription Term = 1 billing period
• Auto-Renew Term
• Annual Auto-Renewing Subscription Billed Quarterly
• Billing Period = 3 months
• Subscription Term = 4 billing periods
• Auto-Renew Term
• Annual Auto-Renewing Subscription Billed Upfront
• Billing Period = 1 year
• Subscription Term = 1 billing period
• Auto-Renew Term
• Payment Plan for a One Time Purchase
• Billing Period = 1 month
• Subscription Term = 12 billing periods
• Expire

Adding a Subscription

When adding a subscription to an account, the subscription will always default to the plan’s term configuration, but you can further customize.

Timing

This section contains all of the relevant information relating to the start date of the subscription (immediate or future) and the subscription term settings.

Subscription Term

This is the initial term a customer is committed to when subscribing. This value will always default to the plan's subscription term length, but can be customized. For example, a business may have a plan that has a default term of 12 monthly billing periods but they want to extend the customer's term for another year (e.g add 12 additional billing periods). This would lock the customer into a 24 billing period term, that they would be required to complete.

At End of Term Behavior

This is the same setting that exists when creating a plan and will determine whether the subscription should auto-renew for another term once the current term completes or if it should expire at the end of the initial term. When adding a subscription, the end of term behavior will default to the plan's configuration but can be modified.

Renewal Subscription Term

If the subscription is configured to automatically renew for another term, then you will also see a Renewal Subscription Term. This is the commitment for the following subscription term (when the subscription renews). The renewal term will always default to the plan's term length. For example, if a plan has a 12 period term, a subscription to that plan will automatically default to a renewal term of 12 periods unless overwritten.

In some cases, a business may want some of their subscriptions to have a renewal term different from the plan default or the initial subscription term. For example, if you are a business that wants to have your customers committed to a year of service up front before they can move to a month-to-month subscription, you can create a one year subscription, billed monthly, that converts to a month-to-month subscription after a year.

Subscription Details

We've enhanced the designs of our subscription details page to account for the term related details of a subscription. Based on whether the subscription has a single period term or is a multiple period term, we will display certain information.

Subscription Details Can Include

• Current Period: this refers to the current billing period that the subscription is in (e.g monthly billing period)
• Current Term: this refers to the start and end date of the subscription's current term. This will not be displayed if the subscription's term only has 1 billing period
• Remaining Periods: the remaining billing periods in the subscription’s current term. This will not be displayed if the subscription's term only has 1 billing period.
• Term Balance: the remaining amount to be billed for the subscription, calculated by the price per billing period multiplied by the remaining periods (includes fixed price add-ons but does not include setup fee, taxes, or usage add-ons). This is a great way to quickly get an estimate of the remaining amount a customer will be billed. This will not be displayed if subscription's term only has 1 billing period.
• Renews On: If the subscription is configured to auto-renew at the end of the current term, this will be displayed on the subscription details and reflect the date the subscription term will renew.
• Ends On: If the subscription is configured to expire at the end of the current term, this will be displayed on the subscription details and reflect the date the subscription will expire.
• Started On: This is the date that the subscription was activated.

Multiple Billing Period Subscription Term
When a subscription has multiple billing periods in term, we aim to provide all important details relating to the subscription. We display the start and end dates of the term as well as the remaining periods left in the current term. We also show the Term Balance, so that you are able to see the remaining amount to be billed for the subscription based on where the customer is in their current term.

Single Period Subscription Billing Term
If a subscription term is only comprised of 1 billing period, you will be presented with a simplified subscription details card. For example, a customer subscribed to a month to month term plan. The current term start and end date will always be the same as the current period start and end date, therefore we only display the current period.

📘

Remaining Billing Cycles with Auto Renew before and after Subscription Terms

Before subscription terms, remaining_billing_cycles used to mean "How many more cycles will this subscription bill before it ends", where in the subscription terms world, it means: "How many billing cycles will this subscription continue for until it either ends or renews into a new term". If the subscription is set to auto_renew = true, it will renew into a new term. If the subscription is set to auto_renew = false, it will end after the last billing cycle.

The value of auto_renew on the subscription is accurate on both subscription terms and non-terms subscriptions, so auto_renew= false means it's going to expire when remaining_billing_cycles reaches 0 in both versions of terms.

Changing a 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 next bill date, or when the term renews.

Timing of Change

A subscription can be changed immediately or at the next term renewal. Immediate changes will bill the change right away. At next bill date changes will reflect the change on the customers next invoice. At renewal changes will reflect the change on the invoice when the subscription term renews.

Most often we see that merchants prefer to make upgrades immediate and downgrades at next bill date or term 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, subscription term, continuing to provide the customer with the higher value product until the 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.

Note changing the subscription's term length immediately will not result in an invoice if that is the only change taking place.

Immediate change proration logic is outlined in detail here.

At Next Bill Date Changes

When a subscription change's timeframe is set to apply "When subscription next bills", Recurly saves the changes and applies them on the customers next invoice. For example, if you upgrade an annual plan and apply the change for the next bill date, the subscription will be upgraded at the end of the current billing period.

At Term Renewal Changes

When a subscription change's timeframe is set to apply "When subscription term renews", Recurly saves the changes and applies them when the subscription term renews. For example, if you upgrade an annual plan and apply the change for when the term renews, the subscription will be upgraded at the end of the initial annual plan.

One Change Request Maximum

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.

Plan Term Changes

When changing a subscription’s plan, it’s important to keep in mind the differences in the billing structure (billing period, term length) of the new plan that you are switching to.

Change to Plan with the Same Billing Period and Term Length

Immediate subscription changes where the plan term structure stays the same (e.g. Plan A with monthly billing period and 12 period term to Plan B with monthly billing period and 12 period term) will keep the same number of remaining billing periods and follow normal proration rules. After applying the change, the customer will be credited for the remainder of the current billing period and charged for the prorated price of the new plan for the remainder of current billing period. Customer will not start a new subscription term, but continue from the current period in their term. In the instance that you do want to adjust the term length, you will be able to do so.

Change to Plan with Different Billing Period and/or Term Length

If the immediate subscription change is a plan change where the underlying term changes (e.g. monthly billing period and 12 period term to quarterly billing period and 4 period term), the subscription’s term will start over and the new charges will not be prorated.

This also covered in Change Subscription.

🚧

When a subscription is set to expire at end of current term

If you are editing a subscription and applying the changes effective when the term renews but the subscription is configured to expire at the end of the current term, when saving the changes we will automatically update the subscription the renew at the end of the current term and apply the pending changes.

Canceling a Subscription

When a customer elects to end their subscription at their next bill date or at the end of their term, this is called canceling the subscription. If you decide to end the subscription early, mid-cycle, this is called terminating the subscription. Both result in the subscription expiring. Once a subscription is expired, it cannot be reactivated. Only a canceled subscription can be reactivated, which just means the customer changed their mind and decided to continue the subscription before the renewal where the subscription was set to expire. Depending on your business, you may prefer one method over the other.

Terminate Immediately

Terminating a subscription will move the subscription's status from active to expired, immediately. Since terminating expires the subscription in the middle of the billing cycle, you have the option to refund the customer for any fixed fees paid up front, or charge the customer for any usage fees not yet billed.

If the last invoice for the subscription was paid, you will see the option to refund all or a prorated amount of the last invoice. If the subscription includes usage-based add-ons with unbilled usage, you will see the option to not charge the customer for their final usage. Note that a final invoice is always sent if there are usage-based add-ons in the subscription. Choosing to not charge simply reduces the usage shown on the invoice to zero.

Cancel Subscription at Next Bill Date

Although most of your subscribers will likely be subscribed to plans that have auto-renewing terms, there will be customers that may want to cancel their subscription. This option will provide flexibility to cancel the subscription before their next invoice. Choosing this option will ensure that the subscription continues for the remainder of the current period, and then will expire before the next period begins. For example, if a subscription has 6 remaining monthly billing periods in their 12 period term and the subscription is canceled, the customer will keep service until the end of period 6, and then the subscription will expire.

Cancel Subscription at End of Term

Although most of your subscribers will likely be subscribed to plans that have auto-renewing terms, there will be customers that may want to cancel their subscription. This option will allow you to enforce stricter cancelation rules for your customers that may have remaining billing periods in their subscription term. Choosing this option will ensure that the subscription continues billing for the remainder of the current term, and then will expire. For example, if a subscription has 6 remaining monthly billing periods in their 12 period term and the subscription is canceled, the customer will still pay for the remaining 6 billing periods in the term, and then the subscription will expire.

Exports

The Subscriptions Export and Subscription History include the new term attributes for subscriptions.

🚧

Backfilling subscription data

When this feature is enabled, we will automatically run a backfill that will start to fill in the new term attributes for all live subscriptions on your site. What this means for your Subscription and Subscription History exports, is that the additional term related columns, such as total_billing_cycles, will start to populate with the term subscription data attributes. For example, a monthly subscription will have total_billing_cycles value of 1.

Export columns

Emails

We’ve added new Subscription fields that can be used in Recurly’s email templates.

• {{total_billing_cycles}}} integer, number of billing periods within the current subscription term
• {{current_term_started_at}}:datetime, Date when the current subscription term started
  Useful to use in Payment Confirmation email for condition when a subscription is going to billed for another term to display new start date
• {{current_term_ends_at}}:datetime, Date when the current subscription term will end
  If you are creating subscriptions with more than 1 billing period in a term, this field should be used instead of current_billing_period_ends_at to accurately reflect the date of subscription term renewal in the Renewal Reminder email and the date when a change will apply at-term renewal for Subscription Change email.
• {{renewal_total_billing_cycles}}:integer, If subscription is auto-renewing, this is the number of billing periods in the next term.
• {{subscription_term_auto_renew?}}:boolean, Returns true if the subscription is configured to automatically renew for another term after current term is completed.
• {{subscription_term_balance}}
  If the subscription has multiple billing periods, the remaining amount due for the subscription
• {{subscription_remaining_billing_cycles}}
  The remaining number of billing periods in the subscription term
• {{subscription_total_term_amount}}
  The total cost for the subscription, excluding any usage charges and setup fees

Webhooks

We have not made any updates to existing subscription webhooks. If you want to retrieve more information about a subscription’s term details, we recommend a GET call via the API, to lookup an individual subscription’s term attributes.