Pricing & plans 101: Add-ons
Master Recurly add-ons to maximize subscription expansion revenue. Learn to structure optional, required, and usage-based add-ons, utilize the item catalog for multi-plan consistency, and manage critical properties like billing timing, accounting codes, and pricing models.
Acquire · Pricing & Plans 101
Add-ons
Add-ons let you charge for additional features, quantities, or services alongside a plan's base charge. This page covers how they work, how to build them, and when to use the item catalog instead of creating them from scratch.
Navigation Menu
Navigate Home
Add-ons
What is an add-on?
An add-on is an additional charge billed alongside a subscription's base plan price. You define add-ons at the plan level — when a subscriber signs up to that plan, you can include one or more add-ons in the subscription at creation or add them later.
Add-ons are useful whenever part of your offering is optional, variable, or priced separately from the core subscription. Common examples include extra user seats, premium support tiers, additional storage, or one-time setup charges recurring each billing period.
Optional add-ons
Subscriber can choose to include or exclude at signup. Creates a natural upsell opportunity — the core plan stays accessible, the extra value is a clear upgrade.
Required add-ons
Automatically included with every subscription to the plan. Use when the add-on is part of every offering (e.g., a mandatory onboarding fee or platform license).
Editable quantity
Allow the subscriber (or your admin) to set a quantity at subscription creation — useful for per-seat or per-unit pricing where the number varies by customer.
Usage-based add-ons
Charge based on consumption reported each billing period. Billed in arrears — usage is reported, then invoiced. Supports four pricing models: fixed, tiered, volume, and stairstep.
Plan-level add-ons vs. item catalog
When you create an add-on, you have two approaches. The right choice depends on whether the add-on appears on one plan or many.
| Approach | How it works | Best for |
|---|---|---|
| Plan-level add-on | Created directly on a plan. Unique to that plan — if you need the same add-on on another plan, you create it again separately. | Add-ons specific to one plan, or when you want full control over each plan's offerings independently. |
| Item catalog add-on | Created as a reusable item in your catalog first, then attached to one or more plans. Name, code, accounting code, and tax settings auto-populate from the item. | Add-ons that appear across multiple plans (e.g., a "premium support" add-on sold on monthly and annual plans). |
If the same add-on will appear on more than one plan, create it in the item catalog first. This keeps naming, accounting codes, and tax settings consistent across all plans — and means one update propagates everywhere instead of requiring manual edits plan by plan.
Once an add-on is applied to a subscription, that subscription add-on is its own record. Updating the plan add-on later does not affect existing subscriptions — only new ones. Plan your add-on structure before you start creating subscriptions at scale.
Key add-on properties
When you define an add-on — whether plan-level or catalog-derived — these are the fields that shape how it bills.
| Property | What it controls |
|---|---|
| Add-on code | Unique identifier used in API calls. Cannot be changed after creation. |
| Pricing model | Fixed, tiered, volume, or stairstep. Determines how the charge is calculated per billing period. |
| Default quantity | The quantity included in the subscription by default. Can be overridden at subscription creation if editable quantity is enabled. |
| Optional / required | Whether the subscriber must include this add-on or can choose to omit it. |
| Billing timing | Flat add-ons bill each billing period alongside the base charge. Usage-based add-ons bill in arrears after usage is reported. |
| Accounting code | Internal code for revenue recognition and reporting exports. Auto-populates from the item if using the catalog. |
How to add an add-on to a plan
Add-ons are created within a plan's settings in the Admin Console. You can add them when creating a new plan or edit an existing plan to add them later.
Open the plan
Go to Configuration → Plans, then select the plan you want to add an add-on to. Click Edit.
Choose your approach
In the Add-Ons section, choose to create a new plan-level add-on from scratch, or select an existing item from your item catalog. Catalog-based add-ons auto-populate name, code, and accounting settings.
Set the add-on properties
Configure the add-on code, pricing model, price, default quantity, and whether it's optional or required. If usage-based, set the billing timing to arrears.
Save
Click Save Changes. The add-on is now available on this plan. New subscriptions to this plan can include it; existing subscriptions are not affected until you explicitly add it to them.
Add-ons as a packaging strategy
Add-ons are not just a billing mechanism — they're a packaging decision. How you structure them determines what your checkout experience looks like and how you capture expansion revenue over time.
Three questions to settle before building add-ons
- Is this a permanent part of every subscription or an optional upgrade? Required add-ons work for mandatory fees; optional add-ons are better for upsells you want to grow over time.
- Does the quantity vary by customer? If yes, enable editable quantity so each subscription can reflect what that customer actually purchased.
- Will this add-on appear on multiple plans? If yes, create it in the item catalog before attaching it to any plan — not as a one-off plan-level add-on.
Not sure how to structure your add-ons?
Add-on architecture has downstream effects on reporting, checkout, and expansion revenue. Bring your packaging questions to Global Office Hours — live sessions with Recurly CSMs every week.
Register for Office Hours →