Getting Started

Building Blocks

Subscription Features




Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Attach Additional Data


Open Source Resources

Other Features

API Integration

Third Party Integrations


To sign up a new subscription, and to charge a customer, we need to know how much and how often to charge them. To do this, we need a Plan.


What constitutes a Plan? 

A Plan is made up of price and billing intervals which you would use to sell subscriptions and charge buyers.

Considering the various kinds of subscription packages you can offer, you can easily create multiple Plans to accommodate them. Let us consider the example of an online storage solution provider throughout this document:

For example, there will be some users who will buy storage space for personal use while others would buy it for their business. You can create a home plan that provides basic features and a professional plan encompassing the advanced features at a higher price.

Quantity Based Plans vs. Flat Fee Plans 

When creating Plans, you can specify the Plan's recurring charge model. There are two options:

  1. Per Unit
  2. Flat Fee

Per Unit

If the product offering is quantity-based, you can create your Plan using this option. You can specify the plan quantity during sign up through the hosted pages or when creating subscriptions using the API .

The quantity of a Subscription can always be changed if required, by updating the Subscription.

Flat Fee

Use this option to create Plans with a fixed price and for which the quantity will always be 1. You cannot add quantity for these Plans.

Can I add/edit plans after initial setup? 

There is no limit to the number of Plans you can create. You can keep adding Plans whenever you need them.

When editing an existing Plan that has no subscriptions linked to it:

  1. You can make changes to all the fields.
  2. Plans that have no subscriptions associated with it can be completely deleted and the Plan Name can be reused.

When editing a Plan that has subscriptions linked to it:

  1. You can only change the Plan Name, invoice name, and id.
  2. You can also archive a Plan if you no longer need it but the Subscriptions that are linked to it would be retained.
  3. No new Subscriptions can be added.
  4. The Plan's state will be displayed on the web interface as Archived.
  1. A Plan Name has to be unique. Even if a Plan has been archived, the name cannot be reused unless the Plan has been deleted.
  2. If a Plan has been archived, existing subscribers will still continue to be renewed.
  3. To change the price currency, go to SettingsSite info.

Deleting Vs. Archiving Plans 

Deleting and archiving depends on whether the Plan has any Subscriptions associated with it.

When you delete a Plan that has no subscribers, the plan is completely removed from the system and it will not appear on the list of plans either. You can reuse a deleted Plan's name to create a new Plan if needed.

When you delete a Plan that has existing subscribers then the Plan gets archived. This means that it is not completely removed but will be in archive mode and will appear on the list of Plans. Archiving will also prevent future usage of the Plan.

Creating a new Plan 

Creating a new Plan is quite simple. All you need to do is:

  1. Log into your web interface.
  2. Go to Product CatalogPlansCreate a New Plan.

Fill out the new Plan form with all the necessary details and you're all set.

What do I name my Plan? 

Naming a Plan (using the Name field) is mandatory, and it should be named in a way that is easily identifiable without having to go into the actual Plan to see the details.

Rather than naming Plans, Plan A, Plan B, it is quite convenient to name it say, Home Monthly/Yearly, Professional Monthly/Yearly, etc.

What is the ID field used for? 

The Chargebee API uses the unique Plan id and not the Plan name to identify the plans that are on your website. A plan ID is the unique identifier of the Plan and when a Subscription is created or updated via the API from your app/website, the "id" should be used to refer to the plan.

Here's a sample Curl API code:

Click here  to see our API.

Where is the invoice name used? 

This would appear on the invoices, hosted checkout page and the customer portal.

What is the plan description for? 

The description content you enter for the Plans are shown to your customers in the customer portal when they change their subscription.

What are the accounting fields for? 

The Accounting Information section helps Chargebee sync up with any accounting applications that you integrate with, like Xero and Quickbooks. Each of the accounting fields captures information that helps track product specific sales/revenue from an accounting perspective.

  • Accounting code: This field captures your Accounting systems' General Ledger Account code/name. When product information is synced to the Accounting system, the product specific information will be synced with this account as captured here. This is a mandatory field. You cannot proceed with accounting integration if this field is left blank.

  • Accounting category: The Accounting Category captures product specific additional metadata or categorization for reporting purpose in the accounting systems (such as regions you are selling to or branches you are selling from). It should be entered in the format: : (example: Region: North).

If you are using QuickBooks - you can enter one category (referred as Classes/sub-classes)

If you are using Xero - you can enter two categories, Accounting Category_1, Accounting Category_2 (referred as Tracking categories).

For information regarding these fields in API, refer the plans section in the API documentation .


These fields will not be available by default, you should enable these fields at Settings > Site Info > Enable Accounting Fields.

Restricting plans in the Customer Portal 

To hide a plan from appearing for selection in the Customer Portal (during the Change Subscription operation), uncheck the option Display in Customer Portal in the Create New Plan/Edit Plan page:

Pricing and billing interval 

The Price field is used to specify how much you are charging the buyer for the particular plan.

Once you have set the price, you can set the billing interval using the Bill Every field. This determines how frequently the customer has to be charged.


Price: $50

Bill Every: 3 Months

This will charge the buyer at $50 every three months.

If it is a quantity based plan, then the price will be $50 * Quantity.


Price: $50

Bill Every: 3 Months

Subscribed Quantity: 5

The buyer will be charged $50*5=$250 every 3 months.

Can I add a onetime setup fee? 

Yes. Using Setup Cost (which is an optional field) we can setup a onetime fee along with the first payment.


If you provide a onetime installation support for the storage application suite, you can use
Setup Cost for charging the customer once during the sign up.

You could also use non-recurring Addons but to be able to do so, the plan should not have a trial period.

Setting subscription duration 

You can use the No. of Billing Cycles field to determine the subscription duration. If you leave this field blank, it will default to being charged until you or the customer cancels the subscription.

The billing cycle is used to set the number of recurrences for charging the customer.


You want to charge a customer on a quarterly basis for 1 year.

Bill Every: 3 Months

No. of Billing Cycles: 4

Subscription Ends after: 3 * 4 = 1 year

Total Charges Made: 4

I want to edit the price of Plan that already has subscriptions? How can I do that? 

Yes, you can change the price of a Plan associated with Subscriptions. Depending on whether you want to tailor the price to a particular customer, update an old plan or create a new plan populated with the same details, you can either clone the plan, edit it or override the price of the plan for a particular subscription.

Clone the Plan

Cloning a Plan involves replicating an existing Plan to make changes to it. You can also use this option to increase the plan price for new subscriptions while keeping your existing subscriptions on the old price. Alternatively, if you want existing subscriptions to be charged onto the new price, you can use the Change Subscription option.

You can make the following changes using the Clone Plan option:

  • Changes related to the pricing and billing model.
  • Trial periods can be changed with this option.

Here's how you can clone a Plan:

  1. Select the Plan you want to make changes to.

  2. Click the Clone Plan option available on the Actions panel.

  3. If you would like to retain the original plan name for current subscriptions, then rename your existing Plan name and plan id by adding a suffix ‘v1' or ‘ old'.
    (Make sure you copy and store the original plan name and id before renaming it).

  4. Once you have renamed the Plan, use the original plan name and id to create the new cloned Plan.

Existing subscriptions will continue to be charged based on the old price, while new subscriptions will be charged based on the the new plan price.


Ensure that you archive the old Plan after cloning as soon as possible so it does not appear in the Customer Portal. Associate the cloned Plan with the respective plan at your end (website) so that new customers are able to see only the new plan.

Override the price of the plan for a particular subscription

If you would like to change the price of a plan for a particular subscription or set of subscriptions without modifying other facets of the plan or making a new one, Chargebee allows you to override the price of a plan.

Here's how you can customize the price of a plan to a particular subscription:

  • Navigate to the customer's subscription details page and click the Change Subscription option listed under Actions.

  • On the Edit Subscription page, enter the new price in the Unit Price field and the quantity for which you'd like the new price to apply. All invoices for this subscription will be made with reference to this new price.

I want to set a custom price for an existing plan. How can I do that? 

Chargebee allows you to override the price of a plan for a particular subscription. All invoices generated for the subscription will cite this new amount.

You can override the price of a plan when creating the subscription or if you'd like to set a custom price for an existing subscription, you can:

  • Navigate to the customer's' subscription details page and click the Change Subscription option listed under Actions.

  • On the Edit Subscription page, enter the new price in the Unit Price field and the quantity for which you'd like the new price to apply. All invoices for this subscription will be made with reference to this new price.

How are free trials handled? 

Using the Free Trial field you can set the number of days an account can be in trial mode. Depending on the payment gateway you use, once trial days are over, the initial charge may go through. Read more.

How can I use free quantity? 

This option is available when you specify your plan's recurring charge model as Per Unit.

Free quantity is the amount of goods you would like to give to your customers at no extra charge. You or your customer can specify the total quantity of goods at the time of purchase.

This plan is only applicable for quantity-based plans.


If a customer is signing up for a special discounted plan that offers 10GB at no charge.

Price - $2

Free Quantity - 10 GB

Subscribed Quantity - 100 GB

Quantity Chargeable - 90 GB

Charged Amount = $2 * 90 = $180

So this customer will only be charged for 90 GB of storage space.

If the free quantity is more than the subscribed quantity, then the plan will be considered as a free plan, and the buyer will not be charged at all for his subscription. For the above example, if the subscribed quantity was 10 GB, then it would be a free plan.

Grandfathering Existing Plans 

You would resort to grandfathering when you want to increase your plan costs for your new customers but exempt your current customers from it.

Here's what you need to do:

  1. Change the plan name and plan ID on the current plan and archive it but note down the old plan ID before archiving it.
  2. Create the new plan with the latest price details. Use the old plan ID and old invoice name.

You have a plan named "Standard" and the cost is $10/month. After sometime you decide to change your pricing structure to $15/month. So you would first rename the old plan to something like "Standard V1" for your reference. Rename the plan ID to something similar as well. Then archive this plan if you want to prevent it from being used in the future.

Create a new Plan and name it let us say "Standard V2" with the plan cost as $15/month. Use the old Plan's ID and invoice name for your new plan.

Your website will still continue to say "Standard" for new subscribers with the new price and you will not need to update any links or make any changes to your site.

So what really happens is that all your existing subscribers will remain on the "Standard V1" plan with the old pricing structure and all your new subscriptions will be pointed to the new "Standard V2" plan and will be charged based on the new price. And both your existing and new customers will get their invoices with the same invoice name.

We would recommend that you make these changes during non-business hours.