Plans

How to create, configure, update, duplicate, and delete subscription plans in Recurly — including billing cycles, pricing models, price segments, and add-ons.

Plans are the blueprint for your subscription business — they define what your customers subscribe to, how often they're billed, and how much they pay. Whether your model includes free trials, setup fees, ramp pricing, or price segments, Recurly's plans are built to match your business exactly. There's no limit to the number of plans you can create.

✦ Available on all Recurly plans

Plans dashboard

Your plans dashboard lists all plans defined in your Recurly account. Select any plan name to view its details, edit it, or link to its Checkout configuration or Hosted Payment Page.

1Definition 2Key benefits 3Create a plan 4Update a plan 5Duplicate a plan 6Delete a plan

Definition

A Recurly plan defines the billing frequency and base price for a subscription product. Plans support free trials, setup fees, multiple pricing models, and add-ons — giving you the flexibility to model any subscription business without limits on how many plans you create.

Key benefits

✦

Flexible plan configurationSet billing cycles, trial periods, setup fees, renewal behavior, and pricing models — all in one place, tailored to how your business actually works.

✦

Multiple pricing modelsChoose from fixed, ramp, or usage-based pricing to match your revenue strategy, with price segments for A/B testing and market-specific pricing without plan sprawl.

✦

Built-in upsell with add-onsAttach optional products and services to any plan to increase customer value and drive incremental revenue without creating separate plans.

Create a plan

Open the new plan form

Navigate to Configuration → Plans and click New Plan.

Define plan parameters

Fill in the sections below. Work through each configuration group in order — plan details first, then billing, pricing, and the optional extras.

Plan details

Field	Description
Plan name	Describes your plan. Appears on the Hosted Payment Page and the subscriber's invoice. Limit: 255 characters. Check with your payment gateway before using special characters.
Plan code	Your plan's unique identifier in Recurly. Used in Hosted Payment Page URLs and API requests. Limit: 25 alphanumeric characters.
Plan description	Describes what the plan includes. Appears on the subscriber's email invoice if configured in your email templates.

Plan configuration

Field	Description
Currencies	Choose which of your enabled currencies to include in this plan.
Free trial	Define a free period in days or months. The paid subscription starts after the trial ends. Choose whether to require billing information at sign-up.
Setup fee	A one-time charge processed at sign-up.

Billing configuration

Field	Description
Billing period	How often a subscriber is billed.
Subscription term length	The default length of time customers are committed to the subscription. Subscriptions always renew with this term unless modified at the individual account level.
Billing cycles	Choose to automatically renew or expire the subscription after a set number of billing periods, configured in the "At end of subscription term" section.

Pricing model

Field	Description
Pricing model	Choose fixed or ramp pricing to match your subscription model.
Price	Set the fixed price charged to plan subscribers. For quantity-based pricing, use add-ons.

Price segments

Price segments let you define multiple price points for a single plan within the same currency — useful for A/B testing or market-specific pricing without creating duplicate plans. A default price is always required and applies whenever no segment code is provided.

Example: You run a gym where operating costs vary by city. Rather than cloning identical plans, create one plan with segments — default, nyc, la — and apply the right price at checkout based on the customer's location.

How price segments work

Recurly stores all segment prices and the default price on the plan
You decide which price to apply (by geography, campaign, experiment bucket, etc.) — Recurly doesn't choose the segment for you
Segment data (code and price) is returned via the v3 API and Recurly.js so your checkout can display the intended price

Implement price segments

Add segments to the plan

In the plan's Pricing section, create one or more segments and set a default price.

Define your selection rule

For example: if city=NYC use segment nyc; if the user is in test group B, use segment exp-b.

Surface the right price in your UI

Fetch the plan's price segments via the API or Recurly.js and render the price that matches your rule.

Apply the segment at checkout

When creating the purchase or subscription, pass the chosen segment's price. If no segment is provided, the default price is used.

TipFor A/B tests, name segments clearly — for example, exp-a, exp-b — and log the chosen segment code with your analytics events.

Notes and limits

Detail
Number of segments	No limit per currency
Availability	Plans only (fixed and ramp pricing). Not available on setup fees, add-ons, items, or Recurly Checkout.
Adding segments	You can add segments to existing plans at any time
Editing segments	After creation, only the price within a segment can be edited — the segment code is fixed
Invoice visibility	Segment codes don't appear on invoices or in email templates — they're for your internal selection logic only

Developer references

Billing details

Field	Description
Accounting code	A unique code to identify this plan in your internal invoice exports. Configure based on your tax settings and compliance requirements. Limit: 25 lowercase alphanumeric characters.
HS code / Commodity code	An HS or Commodity code for invoice compliance on traded products. HS codes are at least six digits, with countries adding digits for regional classification. Limit: 25 lowercase alphanumeric characters.

Plan add-ons

Optional products that can be included in a recurring subscription's invoices. Add-ons also support quantity-based pricing models. You can add items directly from your item catalog to a plan.

Dunning campaign

Select the dunning campaign to apply to this plan.

Customer emails

Check the boxes to enable email communication for specific billing events. You can modify and manage your templates on the Email Templates settings page.

Hosted Payment Pages

Field	Description
Plan quantity can be edited	Determines whether subscribers can choose their own quantity on the Hosted Payment Page.
Return URL after success	Redirects the customer to a specific URL after a successful transaction via the Hosted Page.
Bypass Recurly confirmation	Skip Recurly's confirmation page and send the customer directly to your custom return URL.

Create the plan

Once all parameters are configured, click Create Plan to finalize.

Checkout configuration

After creating a plan, you can set up a Checkout configuration to direct customers to purchase it.

Update a plan

Navigate to plans

Go to Configuration → Plans.

Select Edit

Hover over the plan row in the list view, or use the plan actions menu on the plan details page, and select Edit.

Plan row hover actions showing Edit, Duplicate, and Delete options

Save your changes

Make your changes and click Save Changes.

Plan name changes apply to existing subscriptionsUpdating a plan's name updates it site-wide. Existing subscriptions will show the new name in the Admin UI, and future invoice line items will use the updated name.

NoteVersioned plan terms — such as price, billing interval, and setup fees — apply to new subscribers only. Existing subscribers keep the terms that were in effect when they signed up.

Duplicate a plan

Navigate to plans

Go to Configuration → Plans.

Select Duplicate

Hover over the plan row to reveal the action options, then select Duplicate. All details from the original plan are copied to the Create a Plan form, with -copy appended to the plan name and plan code.

Duplicate plan form with -copy appended to name and code fields

Adjust the details

Update the plan name, plan code, and any other fields as needed for the new plan.

Create the plan

Click Create Plan once you've finished adjusting the details.

TipYou can also duplicate a plan immediately after creating it — the success confirmation includes a duplicate option.

Delete a plan

Navigate to plans

Go to Configuration → Plans.

Select Delete

Hover over the plan row in the list view, or use the plan actions dropdown on the plan details page, and select Delete.

Confirm deletion

Confirm your decision in the dialog.

WarningDeleting a plan is permanent and prevents new customers from subscribing to it. Existing subscriptions continue to renew, but once deleted, a plan can't be reactivated. Subscriptions tied to a deleted plan cannot be edited — including frequency, price, and add-ons.

Updated about 19 hours ago