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.
Dashboard
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.)
- 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 invoice.
- Accounting Code
- A value to help identify subscription plans in internal invoice exports. (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.
- 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 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.)
- 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 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.
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.