Overview

Required plan

This feature or setting is available to all customers on any Recurly subscription plan.

Definition

Recurly plans are the blueprint for your subscription business, orchestrating the frequency and amount your customers are charged. Whether your model includes free trials, optional add-ons, or initial setup fees, Recurly’s plans are designed to be a perfect match for your distinct business needs—and there’s no limit to the number of plans you can create.

Key benefit

• Tailored plan creation: Mold your subscription plans with Recurly to fit your business like a glove. Configure options like:
  • Trial periods: Roll out enticing free or discounted trials to potential customers.
  • Setup fees: Implement one-time setup fees where applicable.
  • Billing cycle lengths: Specify the intervals for your billing cycles, from weekly to annually.
  • Subscription term lengths: Designate the length of subscription commitments.
  • Renewal options: Opt for subscriptions that either auto-renew or expire at term end.
  • Pricing models: Choose from fixed, ramp, or usage-based pricing to align with your revenue strategy.
  • Price segments: Create different price points with a single currency for specific customer segments on a single plan.
  • Add-on features: Augment plans with added services or products to upsell and enhance customer value.

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 Checkout configuration or Hosted Payment Page.

Creating a plan

Step 1: Create a new plan

From your main plan page, navigate to Configuration→Plans. Click on "New Plan."

Step 2:Define parameters

Plan Details

• Plan Name: This name describes your plan and appears on the Hosted Payment Page and the subscriber's invoice. Limit to 255 characters. Check with your payment gateway provider before using special characters.
• Plan Code: This is your plan's unique identifier on Recurly. It's used in Hosted Payment Page URLs and API fetch requests. Limit to 25 alphanumeric characters.
• Plan Description: Describe what the plan includes. This will appear on the subscriber's email invoice, if configured in email templates.

Plan Configuration

• Currencies: Choose which of your enabled currencies to include in your plan.

• Free Trial: Define a free period for the plan in days or months. The paid subscription starts after the trial period ends. Choose whether to require billing information at sign-up, offering flexibility to reduce initial barriers for new customers.

• Setup Fee: Include a one-time charge that is processed at the time of sign-up.

Billing Configuration

• Billing period: Set how often a subscriber will be billed.

• Subscription term length : Set the default length of time that customers are committed to a subscription. A subscription to this plan will always renew with this term unless the account’s individual subscription term is modified.

• Billing cycles: Decide to automatically renew or expire the subscription after a set number of billing periods in the “At end of subscription term” section.

Pricing Model

• Pricing model: Set the pricing model that best suits the subscription. Choose from fixed or ramp, accordingly.
• Price: Set a fixed price to charge to a plan's subscribers. For Quantity-Based Pricing, use Add-Ons.

Price segments

Use price segments to define different price points for a single plan within the same currency. This helps you A/B test pricing and avoid plan sprawl. A default price is always required and will be used whenever no segment code is provided.

Example (by location): You own a gym and operating costs are higher in certain cities. Instead of cloning identical plans, create one plan with multiple price segments—e.g., default, nyc, la.

How it works

• Recurly stores all segment prices and the default price on the plan.
• You decide which price to show or apply (geography, campaign, experiment bucket, etc.). Recurly does not choose the segment for you.
• Segment price data (segment code and price) is returned in our v3 APIs and Recurly.js so your app or checkout can pick and display the intended price.

Implement it (quick path)

1. Add segments on the plan. In the plan’s Pricing section, create one or more segments and set a default.
2. Decide your selection rule. For example: if city=NYC use segment nyc; if user is in test group B, use segment exp-b.
3. Expose the right price in your UI. Fetch the plan’s price segments via API or Recurly.js and render the price that matches your rule.
4. Use the matching price at checkout. When creating the purchase/subscription, apply the chosen segment’s price. If you don’t provide a segment, the default price is used.

Tip: For A/B tests, name segments clearly (for example, exp-a, exp-b) and log the chosen segment code with your analytics event.

Notes and limits for price segmentation

• No limit to the number of price segments per currency.
• Available only on plans (fixed and ramp).
• Not available on setup fees, add-ons, items, or Recurly Checkout.
• You can add segments to existing plans at any time.
• After creation, only the price within a segment can be edited; the segment code stays the same.
• The segment code is not shown on invoices or in email templates (it’s for your internal selection logic).

Developer references

• v3 APIs: Use the plan pricing returned by APIs to select and apply the correct price segment.
• Recurly.js: Surface the right price segment in your front end with Recurly.js.

Billing details

• Accounting code: Select a unique code to identify plans in your internal invoice exports. This code should be configured based on your specific tax settings and compliance requirements. Limit to 25 lowercase alphanumeric characters.
• HS code/Commodity code: Enter a Harmonized System (HS) code or Commodity Code to meet invoice compliance requirements for traded products. Generally, HS Code consists of at least six digits, with countries adding more digits for further national or regional classification. Recurly limits to 25 lowercase alphanumeric characters.

Plan Add-ons

• Add-ons: Optional products that can be included in a recurring subscription's invoices. Also supports Quantity-Based Pricing Models. You can add items from the Item Catalog to a plan.

Dunning Campaign

• Dunning campaign: Select the dunning campaign for this plan.

Customer Emails

• Select the emails: Check the boxes to enable email communication on specific matters. You can also modify and manage your templates on your Email Templates setting page.

Hosted Payment Pages

• Plan quantity can be edited: Determine if subscribers can choose their own quantity on the Hosted Payment Pages.
• Return URL after Success: After a successful transaction via the Hosted Page, redirect the customer to a specific URL.
• Bypass Recurly Confirmation: If using the Hosted Payment Pages, choose to bypass Recurly's confirmation page and use a custom return URL.

3. Once all parameters are defined, click "Create Plan" to finalize.

Checkout configurations

After a plan is configured, you can create Checkout configuration to direct customers to purchase your plan(s).

Updating plans

1. Navigate to Configuration→Plans.

2. Either from the plan list view (right option hover) or the plan actions drop down menu on a specific plan detail page, select "Edit."

3. Make the desired changes and click "Save Changes".

Note: Changes will apply to new subscribers only. Existing subscribers will continue with the plan terms present at the time of their signup.

Duplicating plans

1. Navigate to Configuration→Plans.

2. Hover over any row to reveal 3 additional options, then select "Duplicate".

3. All details of the original plan will be copied to the "Create a Plan" page. "-copy" will be appended to the "Plan Name" and "Plan Code" fields.

4. Adjust these field names and modify any other fields as required for the new plan.
5. Click "Create Plan" once you've finished adjusting the details.

Note: You can also duplicate plans after creating a plan. On the success info alert once a plan is created, there is an option to duplicate it.

Deleting plans

1. Navigate to Configuration → Plans.

2. Either from the plan list view (right-option hover) or the plan actions dropdown on a specific plan detail page, select Delete.

3. Confirm your decision.

Notes:

• Deleting a plan is permanent and will prevent new customers from subscribing to it.
• Existing subscriptions to this plan will continue to renew, but once a plan is deleted, it cannot be reactivated.
• Any subscriptions tied to a deleted plan cannot be edited (e.g., frequency, price, add-ons) after the plan has been removed.