Subscription Plans & Add-ons

A subscription plan tells Recurly how often and how much to charge your customers. Subscription plans can be created with free trials, optional products (called add-ons), setup fees, and more. Merchants can create an unlimited amount of subscription plans in their Recurly site.


Your subscription plans dashboard contains a list of subscription plans defined in your Recurly account. You can click on any plan name to view detailed plan information, edit the plan, or link to that plan’s Hosted Payment Page.

Creating a Subscription Plan

From your main subscription plan page, click New Subscription Plan. To create a new subscription plan you’ll need to define the following parameters:

Plan Name
This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice. (255 character limit.) Please note that your payment gateway may also place limitations on your subscription name, so it may be best to avoid special characters without checking with your gateway provider.
Plan Code
This is the plan's unique Recurly identifier and is used in Hosted Payment Page URLs and to fetch plans via the API. (Alphanumeric characters only. 50 character limit.)
Plan Description
A description of the plan that will appear on the subscriber's email invoice, if configured in email templates (not displayed by default).
Accounting Code
A value to help identify subscription plans in internal invoice exports. (Alphanumeric characters only. 50 character limit.) (20 character limit.)
Editable Quantity?
Whether or not subscribers can choose their own quantity.
Billing Cycles
Automatically terminate subscriptions after a defined number of billing cycles.
Base dollar amount charged to a plan's subscribers.
Billing Interval
The frequency with which a subscriber is billed.
One Time Setup
A one-time charge processed at the time of sign-up.
Free Trial
Time the subscriber is allotted on the plan for free. Definable in days or months. The paid subscription will begin at the end of the trial period.
Optional products that can be rolled into a recurring subscription's invoice.
Return URL after Success
After Recurly has been able to successfully subscribe your customer via the Hosted Page, you can redirect the customer to a specific URL. Use {{account_code}} and {{plan_code}} to pass in the subscriber's information. E.g.,{{account_code}}&plan={{plan_code}}
Return URL after Cancel
This setting only affects version 1 of our Hosted Payment Page. If a customer cancels a subscription via the Hosted Page, Recurly can redirect the customer to a specific URL. Use {{account_code}} and {{plan_code}} to pass in the subscriber's information. E.g.,{{account_code}}&plan={{plan_code}}
Bypass Recurly Confirmation
If selected, the customer will be sent directly to your Return URL after Success upon success, bypassing Recurly's hosted confirmation page.


An add-on is a charge billed each billing period in addition to a subscription’s base charge. Each subscription plan may have one or more add-ons associated with it. You’ll define your add-ons when creating or editing subscription plans.

Subscribers can use the Hosted Payments Pages to view and select from the available add-ons. API users can specify add-ons when creating or updating subscriptions.

Add-ons can be customized with the following properties:

Add-on Name
Describes your add-on and will appear in subscribers' invoices. (255 characters limit.)
Add-on Code
Identifies the add-on in Recurly. Must be unique per plan. (50 character limit.)
Amount to bill for this add-on
Editable Quantity?
Whether or not a customer can choose their own add-on quantity.

Updating and Deleting Plans

Editing a subscription plan will change the subscription terms for new subscribers only—existing subscribers will continue with the subscription plan terms present at the time of their signup.

Deleting a subscription plan will prevent customers from subscribing to a plan. Existing subscriptions will continue to renew.

Setup Fees

Setup fees are a one-time transaction charged automatically at the beginning of a subscription billing cycle. For subscription plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a subscription plan.

Free Trials

Subscription plans have an optional trial period that may be specified in days or months. The paid subscription will begin at the end of the trial period.

When Recurly processes a new subscription request, it will attempt to charge the full subscription price for subscriptions without a trial. If the subscription has a trial, Recurly will attempt to validate the credit card using a $1.00 authorization (and will immediately void the transaction). If the subscription is canceled any time before the end of the trial, the account will not be charged and the subscription will expire at the end of the trial. Otherwise, the subscription will be billed normally at the end of the trial.

Recurly does not allow accounts to have trial subscriptions without a valid credit card. If you choose to offer trials without credit cards, your application can track the state of the trial and then make the subscribe API calls to Recurly when the trial ends.

Billing Information Required

Recurly requires valid billing information on an account before a subscription can be applied. We recommend tracking free trials or free subscribers outside of Recurly and adding them into the Recurly interface only when they are ready to become paying subscribers.

Hosted Payment Pages

By default, every subscription plan created inside of Recurly will have its own Hosted Payment Page. This is a Recurly-hosted checkout page customers can use to purchase a specific subscription plan. When inspecting a subscription plan’s details page, click View to open that plan’s Hosted Payment Page. Please see our Hosted Payment Page documentation for more information on configuring this view.