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    

Subscriptions

Subscriptions are created when your customer's subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer.

Your subscriptions dashboard provides an overview of all accounts with subscriptions managed by Recurly. From this view you can sort your subscriptions by account, plan code, subscription status, subscription creation date, or next subscription invoice date. The filters on this view allow you to bucket accounts by subscription status for easy sorting. Categories overlap and are not necessarily distinct, e.g. the Live filter will return both Renewing and Canceled subscriptions.

All

All subscriptions.

Renewing

Active subscriptions that are active and will renew after the current billing period.

Future Start

Subscriptions that will become active when the start date arrives.

Last Renewal

Subscriptions with limited renewals that will expire after the current period.

Canceled

Subscriptions that will not renew after the current billing period.

Expired

Subscriptions that are no longer active.

Trial

Active subscriptions that are in a trial period.

Paying

Active subscriptions that are no longer in trial.

Creating Subscriptions

An account can be subscribed to a [plan][8] a number of ways:

Please see our getting started guide to see which integration method is best for your business.

To add a subscription using the admin console, open the customer’s account and click the Add Subscription button, then configure the following:

Plan Details

Plan

The subscription's subscription plan.

Currency

The subscription plan's purchase currency. Set to site's default currency.

Price

The subscription's base price per billing period. The default price can be overridden here for an individual account.

Quantity

Default: 1.

Plan Extras (Optional)

Setup Fees

If applicable, this fee will be charged to the customer at the beginning of their subscription

Add Ons

If applicable, these products will be rolled into a recurring subscription's invoice as separate line items.

Billing Details

In this section, merchants can select for a subscription to start immediately, or enter a future start date for the subscription. For subscriptions with a trial period, the subscription trial will start on this date. Merchants can also have a subscription bill indefinitely or for a set number of billing cycles. The subscription will cancel after the final bill cycle has been charged.

Collection Method

Automatic

Charges the billing info on file for the account.

Manual

Generates a manual invoice. This is only applicable to merchants who have enabled the manual payments feature. When this collection method is selected you will have the option to assign a PO number, and will also be able to set the net terms for the invoices.

Multiple Subscriptions

An account may signup for multiple subscriptions, where each subscription is invoiced and billed separately. There are a couple of ways that Recurly supports multiple subscriptions.

  • You can use increase the number of subscriptions with the Quantity field for a plan.
  • You can create multiple subscriptions of the same plan for an account that has separate renewal periods.

To have the multiple instances of the same plan enabled for your site, please contact support@recurly.com. Please note that there is a 60 second delay when creating multiple of the same subscription per an account, unless you use the bulk flag via the create subscription API.

Changing Subscriptions

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.

TIMING OF CHANGE

A subscription can be changed immediately or at the next renewal. Immediate changes will bill the change right away. At renewal changes will reflect the change on the next renewal invoice. It is not currently possible to make an immediate change to the subscription, but bill that change at renewal. Please contact Recurly support if you would like to see this functionality added.

DOWNGRADES AND UPGRADES

In most cases, 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.

DIGITAL VS. PHYSICAL GOODS

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.

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 Modification Enforcement below.

EMAIL COMMUNICATIONS

Both automatic and manually collected subscriptions will issue the Subscription Change email, if enabled, to the customer immediately.

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

CHARGES AND CREDITS

Recurly treats all immediate changes as if they were a complete change in the type of revenue, for example, an upgrade from the Silver plan to the Gold plan. This means that we charge for the new version of the subscription, prorated for the time remaining in the billing cycle, and credit for the old version of the subscription, also prorated for the time remaining in the billing cycle. If the subscription change is not a plan change, rather a quantity change, price change, or adding/removing an add-on, you will still see the entire subscription is rebilled. We do not bill only the difference. Here are some examples:

Example of a Plan Change
An upgrade from the Silver plan to the Gold plan would create these charges and credits:

  • Charge for Gold plan
  • Credit for Silver plan

Example of a Quantity Change
An upgrade on the same AcmeCRM plan from 5 users to 7 users would create these charges and credits:

  • Charge for AcmeCRM with quantity 7
  • Credit for AcmeCRM with quantity 5

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

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 cycle divided by the time in the subscription's plan 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 renews at the end of the 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 cycle. 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 cycle / subscription's plan period) x (per unit price)

Or more specifically...

[(current billing cycle 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 billing cycle. This is because the billing cycle can be customized through the postpone feature. If the billing cycle end 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.

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 cycle 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), the subscription billing cycle will start over and the new charges will not be prorated.

Example Change with Same Period
Customer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the monthly Gold plan on May 20, 2016.

  • 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 20 - June 15, 2016
  • Change invoice will have a prorated credit for Silver with dates of May 20 - June 15, 2016

Example Change with Different Period
Customer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the yearly Silver plan on May 20, 2016.

  • Subscription will now have a billing cycle of May 20, 2016 - May 20, 2017
  • Change invoice will have a full charge for yearly Silver with dates of May 20, 2016 - May 20, 2017
  • Change invoice will have a prorated credit for monthly Silver with dates of May 20 - June 15, 2016

AT RENEWAL CHANGES

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

If you want to update a pending change, please submit the original change plus the updated information. Today, the only parameters are: subscription plan, quantity, and unit amount. Pending changes can be cleared by updating the subscription Immediately with no other changes.

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 successful transaction on upgrades
When upgrading an existing subscription, require that 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, 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."

PLAN CHANGES AND GRANDFATHERING

If a subscription's underlying plan is altered, 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. Price grandfathering does not apply to changes in bill cycle (ie, monthly to yearly), however, so changes to billing frequency should be made with a new plan.

Postpone Subscription Renewal

By default your subscribers are billed on the anniversary date of their subscription signup. If this date needs to change for any reason, a subscription can be postponed. This is the same thing as changing the subscription's next renewal date. A postponed subscription will receive no further invoices until the postpone date occurs, unless you make an immediate subscription change.

When a subscription is postponed, the billing cycle dates will be permanently modified for all future renewals. For example, a yearly subscription with a billing cycle of May 15, 2016 - May 20, 2017 that is then postponed to be May 15, 2016 - Dec 10, 2016 will at renewal change the cycle to Dec 10, 2016 - Dec 10, 2017.

BACKDATE A SUBSCRIPTION

Shortening the renewal date through the postpone action can be used to backdate subscriptions in Recurly. This is more common for B2B merchants where contracts are being signed and the customer has actually started the subscription before you are able to add them to Recurly and bill them.

Add the customer's subscription to Recurly while they are still in their first billing cycle. This will bill them the full amount of the subscription, or whatever custom amount you enter when adding the subscription. The start date in Recurly will not match when the customer actually started, but now you can postpone the subscription's renewal to realign the dates. On the Subscription Details page for the subscription, click on "Change Renewal Date" and select the renewal date that matches the next renewal for the contract or your own system. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription.

PAUSE A SUBSCRIPTION

Extending the renewal date through the postpone action can be used to pause a subscription in Recurly. This is useful if you have a customer that is unable to use your product or services for a period of time, but does not want to lose their subscription and you do not want to consider them a churned customer.

Go to the Subscription Details page for the customer's subscription, click on "Change Renewal Date" and select the future date when you want the subscription to start again. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription. As long as you do not do any immediate changes on the subscription, the customer will not be billed again until that new future date.

Immediate changes after postponing by extending will prorate more than 100%

Be careful if you are allowing immediate changes after extending the renewal date. The time remaining could end up being more than the subscription's plan period, which will create charges and credits that are more than the original per unit price.

Canceling and Reactivating Subscriptions

A subscription that is canceled will continue through its current billing cycle. At the end of the current bill cycle the subscription will terminate and the customer will no longer be billed.

To cancel a subscription:

  1. Navigate to the account page.
  2. Click Options under the Subscription.
  3. Click the Cancel Subscription.
  4. Choose the Cancel At Renewal option.

Note: If an account has a past due invoice in dunning, canceling/expiring the subscription will not stop collection attempts on that invoice. The invoice will need to be marked as failed in order to stop collection attempts on the invoice.

Additionally, if a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list.

REACTIVATION

A subscription that is canceled can be reactivated. This will bring the subscription back into an active, renewing state on the customer's original billing cycle. An expired subscription cannot be reactivated; instead a new subscription plan will need to be applied to the account.

To reactivate a canceled subscription:

  1. Navigate to the account page.
  2. Click Options under the Subscription.
  3. Click Reactivate Subscription.
  4. Click the Reactivate Subscription button in the top right corner.

Terminating Subscriptions

A subscription that is terminated will expire immediately. At the time of termination you will be presented with several refund options, if applicable to the account's last invoice. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer's account. You may also terminate a subscription with no refund and then manually refund specific transactions.

To terminate a subscription:

  1. Navigate to the account page.
  2. Click Edit under the subscription.
  3. Click the Cancel Subscription button.
  4. Select the appropriate refund option
  5. Click Terminate Subscription.

Subscriptions

Subscriptions are created when your customer's subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer.