Plans & Add-ons

Dashboard

Your plans dashboard contains a list of plans defined in your Recurly account. You can select 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, Configuration>Plans, select 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. Your payment gateway may also place limitations on your subscription name, so avoid special characters without checking with your gateway provider first.)

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. (25 character limit. Alphanumeric characters only.)

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

Billing Period

The frequency with which a subscriber is billed.

Price

Fixed Price for the amount charged to a plan's subscribers. For Quantity-Based Pricing, use Add-Ons.

Accounting Code

A value to help identify plans in internal invoice exports. (25 character limit. Lowercase alphanumeric characters only.)

Editable Quantity?

Whether or not subscribers can choose their own quantity on the Hosted Payment Pages.

Billing Cycles

Automatically expire or renew the subscription after a defined number of billing periods.

Add-ons

Optional products that can be rolled into a recurring subscription's invoices. Add-ons also offer support for Quantity-Based Pricing Models

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.

Setup Fee

A one-time charge processed at the time of sign-up.

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.

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

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 in the Recurly Admin Console or via the Plans or Add-ons API endpoints.

You can create add-ons that are unique to one plan and the subscriptions to that plan, or create an add-on from a saved item in your catalog that's easily re-usable across multiple plans. When an item-based add-on is defined, many of the add-on's properties are automatically populated with the associated item's attributes.

Add-ons can be customized with the following properties:

Add-on Type

Describes if the Add-on is charged at the beginning of the billing period or the end of the billing period. The documentation below is specific to Add-ons charged at the beginning of the billing period. For more info on usage-based billing, click here.

Add-on Name

Describes your add-on and will appear in subscribers' invoices. For Saved Item add-ons, this will be auto-populated with the item's Name. (255 characters limit.)

Add-on Code

Identifies the add-on in Recurly. Must be unique per plan. For Saved Item add-ons, this will be auto-populated with the Item Code. (50 character limit.)

Accounting Code

An optional field to help identify add-ons in internal invoice exports. For Saved Item add-ons, this will be auto-populated with the item's Accounting Code. (Lowercase alphanumeric characters only. 25 character limit.)

Pricing Model

Describes the pricing model to use for charges. Options are: Fixed Price, Tiered, Volume, and Stairstep. Click (here) to learn more about pricing models.

Price

Amount to bill for this add-on. For Saved Item add-ons, this will default to the item's Default Price, but can be edited.

Tiers

Tiers are used for the Quantity-Based Pricing models. Tiers will be inherited from the plan and can be overridden for a subscription in the Admin Console or API. An add-on can have up to 50 tiers.

Optional Add-on?

Whether or not a customer can subscribe to this plan without the add-on.

Editable Quantity?

Whether or not subscribers can choose their own quantity on the Hosted Payment Pages.

Item-Based Add-ons

To add an item-based add-on to a plan, simply select the relevant item in the Recurly Admin Console or include the Item Code or Item ID for the item in your API request. Add-on Name, Add-on Code, Accounting Code, and any taxation fields must be blank in these requests.

When an item in your catalog is disabled, it will remain active on all existing plans and subscriptions but will be unavailable to add to new plans. The item-based add-on must be removed from existing plans and subscriptions manually if desired. For any plans containing the item-based add-on, new subscriptions with the add-on can be created as long as the add-on remains active on the plan.

In a similar fashion, when an item in your catalog is edited, all original item attributes will be retained on existing item-based add-ons. The add-on must be edited manually on existing plans and subscriptions to update the relevant property.

Configuring Item Add-ons Directly on Subscriptions

If you would prefer to add item-based add-ons directly on customer subscriptions without configuring them and their availability on the plan first, Recurly provides optional functionality to support this subscription model. You can see the details of this feature in our Item Catalog documentation.

Signing Up for Add-ons on Subscriptions

Subscribers can use the Hosted Payment Pages to view and select from the available add-ons on a plan. API and Recurly Admin Console users can specify add-ons when creating or updating subscriptions.

Updating 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 Plans

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

Duplicating Plans

Duplicate a plan instead of starting from scratch! When creating multiple variations of a plan, save time by selecting the option to duplicate a plan from an existing plan. This can be done from the plan list view (right option hover), or via the plan actions drop down menu on a specific plan detail page.

When duplicating a plan, all the the plan details will be copied over into the "Create a Plan" page, allowing modification of the fields for the new plan. Note: "-copy" will be appended to the "Plan Name" and "Plan Code" fields, be sure to adjust these field names to match the new plan.

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

Setup fees and free trials can't be combined using the Hosted Pages. Using the API, 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.

Renewal

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

The 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, select View to open that plan's Hosted Payment Page. Please see our Hosted Payment Page documentation for more information on configuring this view.