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    

Plans & Add-ons

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


Your plans dashboard contains a list of 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 Plan

From your main plan page, click New Plan. To create a new 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 plans in internal invoice exports. (Lowercase alphanumeric characters only. 50 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 Period

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 you use the Hosted Payment Pages, you can bypass Recurly's confirmation page and instead use a custom return URL. When selected, the customer will be sent directly to your Return URL after Success upon success and Recurly's hosted confirmation page.


An add-on is a charge billed each billing period in addition to a subscription’s base charge. Each plan may have one or more add-ons associated with it. You’ll define your add-ons when creating or editing 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 plan will change the subscription terms for new subscribers only—existing subscribers will continue with the plan terms present at the time of their signup.

Deleting a 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 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 plan.

Free Trials

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's billing period 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.

Please note that adding a free trial to a plan will extend the subscription term depending on the length of the trial. For example, an annual plan billed monthly with a 30 day free trial = 13 month long subscription term.

Cardless Free Trials

You have the option at the plan level, to require or not require billing information for your plans with free trials. When you are creating a plan and select a trial length, you will be presented with an option to configure your plan to require or not require billing information at the time of sign-up. A plan must have a free trial in order to configure this setting. You can also edit your existing plans with free trials to not require billing information at sign up.

Setup Fees

If your plan has a setup fee and you do not want to require billing information for your free trial, your customer will need to either redeem a coupon, gift card, or have other credits to cover the total cost of the setup fee in order to bypass the billing information step.

Using Free Trial Coupons

Free trial coupons can be redeemed on any plan. However, in order to bypass the billing requirement on a subscription, the associated plan setting must be configured to not require billing information. If a free trial coupon is redeemed on a plan that requires billing information, this requirement will be enforced.

Changing Your Free Trial Settings

When editing a subscription, if you change your trial setting from not requiring billing information to requiring it, any subsequent subscription sign-ups will respect the new billing requirement setting. For future start date subscriptions with free trials, these subscriptions will respect the billing setting in place when subscription is activated. For example, if a future start date subscription is created to not require billing information and the plan setting changes to require billing information, this subscription will require billing information at activation and expire if billing information is not present at that time.


If a customer has not added their billing information at the time of subscription renewal, the subscription will expire. However, in the case that the invoice at renewal is $0 (there are sufficient credits or gift card credits to cover the cost of the invoice or the plan fee is $0.00) the subscription can renew without billing information.

Trial Ending Email

Trial Ending email allows you to automatically notify your customers 3 days before their free trial ends (trial must be greater than 3 days in order to use this email). Unlike other emails, these emails are enabled on a per-subscription plan basis by checking the respective Send Trial Ending Emails? checkbox when creating or editing a plan. When you enable this email for a plan with a free trial where no billing information is required, we will send a conditional version of the Trial Ending email based on if billing information is present or not 3 days prior to renewal. If billing information is not present, the text of the email body will include information prompting the user to add their billing information.

It is recommended that you enable this email on free trial plans that do not require billing information at sign up.

If you do not wish to use our default template, see Customization and subscriptions fields.

Hosted Payment Page Support

If you use our hosted pages, you will be able to require or not require billing information for your subscriptions with free trials. The checkout page will still present billing information fields, but customers will not be required to provide billing information. We will work to provide a better experience in the future.

Hosted Payment Pages

By default, every 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 plan. When inspecting a 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.