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.

Dashboard

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.

Charge

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.

Add-ons

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., http://example.com/signup/success?account={{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., http://example.com/signup/cancel?account={{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.

Add-ons

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

Price

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

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.