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 are created when your customers subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer.

Subscription Lifecycle


Future subscriptions have a start date in the future. The most common use case for a future subscription is a B2B contract where the subscription is agreed to start on a specific date. The customer is not invoiced until the start date.


Active subscriptions are both regular paying subscriptions and subscriptions currently in a trial.


Canceled subscriptions will automatically expire at the next renewal. A subscription could be in a canceled state because the customer chose to cancel their auto-renewing subscription or the subscription had a fixed number of billing cycles and they are on their last cycle.


Expired subscriptions are churned subscriptions that cannot be reactivated. As subscription can be expired due to involuntary churn by the dunning cycle or voluntary churn by canceling or not renewing their fixed billing cycle contract.

View Your Subscriptions

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


Active subscriptions that are active and will renew after the current billing period. Paused subscriptions are also considered as renewing.

Future Start

Subscriptions that will become active when the start date arrives.

Last Renewal

Subscriptions with a fixed number of billing cycles that are in their last cycle and will expire.


Subscriptions that will not renew at the end of the current billing period.


Subscriptions that are no longer active.


Active subscriptions that are in a trial period.


Active subscriptions that are no longer in trial.

Create a Subscription

To subscribe your customer's to one of your plans, you can create a subscription on the customer's account. A customer can have multiple subscriptions to different plans or the same plan. Learn more

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

Postpone a Subscription's Renewal Date

Postpone a subscription to shorten or lengthen a customer's current billing cycle. Postpone is useful for backdating or pausing subscriptions. Learn more

Expire a Subscription

When a customer elects to end their subscription at the next renewal, 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. Subscriptions with a set number of billing cycles will naturally expire at the end of their last cycle. Learn more


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