When your customers are ready to start paying you, a subscription can be applied to their Recurly account. This subscription will tell Recurly how often 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 subscriptions.
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.
Subscriptions that will not renew after 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.

Creating Subscriptions

An account can be subscribed to a plan 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

The subscription's subscription plan.
The subscription plan's purchase currency. Set to site's default currency.
The subscription's base price per billing period. The default price can be overriden here for an individual account.
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

Charges the billing info on file for the account.
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.

To have the multiple instances of the same plan enabled for your site, please contact 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.

Subscription Changes

Recurly allows your subscribers to easily move between subscription plans, upgrade or downgrade the quantity, and adjust the unit amount. We also let you control when the change occurs: immediately or at the end of the current billing cycle.

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.

For changes that occur immediately, Recurly will:

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.


Typically in an upgrade scenario, a subscriber is moving to a more expensive plan and you would like to receive the money immediately. In this scenario, you would send a change subscription request to Recurly and specify that the timeframe is now. Recurly will perform the necessary prorations to upgrade the subscriber immediately. For more information, see the Subscriptions API.


Downgrade requests typically occur at the end of the current billing cycle. When a subscriber wants to move to a cheaper plan, they have already committed to the more expensive plan for a given duration and you have already collected the funds for that period. To process a downgrade with Recurly, submit a change subscription request and set the timeframe to renewal. Recurly will downgrade the subscription when it renews. For more information, see the Subscriptions API.

Changing Plans

If you offer a monthly and yearly subscription, your users will want to be able to change their billing frequency between the two. These changes are neither upgrade or downgrades. Under ordinary circumstances, the billing cycle adjustment should occur when the current subscription renews. For these adjustments, we recommend setting the timeframe to renewal.

Modification Enforcement

Some merchants may prefer to have their customers current on all payments before allowing a subscription upgrade or downgrade. Recurly allows this to be configurated 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.”


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


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.


A subscription that is canceled can be reactivated. This will bring the subscription back into an active, renewing state on the customer’s original bill 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 Edit under the subscription.
  3. Click the Reactivate Subscription button.


By default your subscribers are billed on the anniversary date of their subscription signup. If you need to pause the subscription, you can postpone the next invoice by changing the next renewal date.

Once you change the renewal date, the subscription will renew on that day moving forward. Changing the next renewal date also extends the current billing cycle. After the subscription renews, the billing cycle will go back to original length of the subscription.

Changing the next renewal date can also be used to renew the subscription early, as long as the date is in the future from today’s date.

Note that changing the next renewal date does not change the status of the subscription. The subscription will still be in an active state, it just won’t charge the customer again until the new renewal date.


John has a gym membership subscription for $30.00 a month that renews every 15th of the month. John gets injured on July 28th and the gym aggrees to postpone his subscription until November 1st.

John receives his next invoice for $30.00 on November 1st and now pays $30.00 every 1st of the month.

Postponement and Subscription Changes

If you postpone a subscription and then change the subscription before renewal, we will prorate based on the new billing cycle length, not the original length. This means you may credit the customer more than expected. In our example, John’s billing cycle changed from a month to three and a half months. If the gym changed his subscription before November 1st, John would be credited a portion of the $30.00 that reflects the amount of time in the three and a half months that was paid for, but not consumed.

If you have postponed a subscription and need to make a change to the subscription, we recommend making the change for “on renewal”.

To postpone a subscription:

  1. Navigate to the account page.
  2. Click More Info under the subscription.
  3. Click the Change Renewal Date button. This will allow you to modify the next renewal date. You can postpone to any date/time as long as it’s in the future.

Trial Extensions

If your subscription is currently in a trial period, you can extend or shorten the trial period by changing the next renewal date for the subscription. Once you change the renewal date, the subscription will renew on that day moving forward.

To change a subscription trial length:

  1. Navigate to the account page.
  2. Click More Info under the subscription.
  3. Click the Change Renewal Date button.
  4. Select the day in the future you would like the trial to end on.


If a subscription plan is altered, the changes will only impact new subscribers—your current subscribers remain grandfathered in at the subscription 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 subscription plan.