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

Subscription Billing Guide 

Subscriptions are the cornerstone of any recurring revenue business model. They usually start simple ($10/month) and grow intricate (with add-ons, promotions, one time payments, the possibilities are infinite) as a business flourishes.

This guide, designed to inform and advise you as you take your first few steps with Chargebee, will tell you how Subscriptions work and how you can make them work for you.

Table of Contents 

Section 1. Basic Setup

Section 2. Taking your setup to the next level

Section 3. The lifecycle of a Subscription

Section 4. Finance Operations - Invoicing and Credit Notes

Basic Setup 

Step 1: Create your catalog of Plans

A Subscription defines how a user associates with one of your Plans. So plans are a good place to start.

A plan maps out the base price, billing frequency, trial period, set up fee, and taxability of your offering. If your product has varying degrees of complexity, is sold per unit, or comes with features that suit different segments of users, your plans can reflect that.

Here's an example of how you could price your product based on the value your customers can derive from it:
Standard - $49 per month
Pro - $99 per month
Enterprise - $999 with a setup fee of $1000

Plans can be structured to have trial periods, trial periods that ask for billing information upfront, or one-time additional services that are offered at sign-up. Your billing workflow and frequency is defined by Plans.

Step 2: Configure settings - Country/Currency/Billing information

With your plans in place, adding details like where you are incorporated and what currency you transact in will allow Chargebee to apply its in-built intelligence to your billing - it will take care of the finer details including tax configurations and compliance requirements. Use this table to input information and configure your tax settings.

Step 3: Set up your checkout experience

Arguably the most important step of the process is choosing how you want your customers to check out of your store after they've decided what they want to buy. Chargebee gives you a couple of options: you could redirect your users to it's checkout page (that you could customize to look like your website) or you could build your own forms and handle the process in-house. Worth considering, is how PCI compliance fits into the two models. Using Chargebee's page delegates security arrangements to us but building your own forms doesn't.

The ideal option is to implement is leverage the API and iframe based hosted checkout pages, that delivers the best of both worlds.

Step 4: Set up a Payment Gateway

A payment gateway is necessary to automate the payments collection process. The online equivalent of a credit card machine, it is where the information that is collected on the checkout page is routed to be processed. Chargebee comes with tested gateway integrations, so all you need to do is configure the gateway credentials to start accepting payments.

With a payment gateway in place, you are ready to start accepting subscriptions on your checkout page.

Step 5: Start signing up customers!

You can either set up a subscription manually or let your customers take care of it themselves.

Most businesses prefer self-service checkout which creates the subscription information in Chargebee. When a customer uses the checkout page to create a subscription to your service, their information is stored securely at Chargebee and is accessible via the API and the web interface.

Going manual is easy too - simply enter the customer's information into Chargebee's web interface. Be sure you request payment information securely though.

Step 6: Synchronizing your application data with Chargebee

Subscription billing is complex by nature: new invoices getting created, scheduled subscription changes made effective, cards being updated, and so on. We've built Chargebee to help you stay on top of the data changes and push information back to your application so that they're always in sync. Here are two ways you can make this sync happen:

1) Real time sync during checkout

When a customer uses a hosted checkout page, Chargebee provides redirect URLs that include customer-specific checkout information. This information is passed back as URL parameters. You could process this information to provide contextual messages and store them as required.

2) Webhooks

A webhook is a notification delivery system for applications, Chargebee can notify your application on what's happening on its end with a webhook. As long as you have a "listener" program running at your end to process the information sent by Chargebee, you have subscription data to act on and a beautiful two-way synchronization between your application and Chargebee.

Just in case information fails to push through, we've built our webhooks to keep retrying the push at incremental intervals, until it receives an acknowledgement from your application. This is to ensure you never fail to get a notification when something is going on.

Taking your setup to the next level 

The steps we've covered so far will get your subscriptions and plans off the ground but they're just the beginning of what you can do with Chargebee, or what Chargebee can do for you. If you want to go full steam ahead, the next few steps will help you be proactive about your subscriptions so your customers are never at a loss.

Step 7: Payment Recovery - Dunning

Unfortunately, it is possible for a transaction that uses stored payment information to fail, and the culprits are usually far from vicious. A maxed out credit card or network malfunction are among the 64 ‘soft failures' that can stop a payment from going through. A simple solution to a soft failure is to try the card again at a calculated, subsequent time. Chargebee can help you automate this procedure, with a set number of attempts at retrying the card and email notifications to customers. Called Dunning management, this automated procedure is worth setting up because card failure can affect your revenue and your customer base if you don't get ahead of it.

Step 8: Integrating with multiple payment gateways

In a recurring revenue business the cost of losing a customer is not just a single transaction; lifetime value of the recurring customer needs to be factored into your decisions. A customer's experience culminates at the checkout page and considering how impactful a last impression can be, it is important to ensure there is absolutely no friction at this stage.

This premise coupled with the near zero cost of using a payment gateway in most countries and Chargebee's multiple gateway support makes the argument for a backup gateway account a no-brainer. A backup gateway guarantees that your present customers can make payments with ease so your new customers can come onboard hassle-free.

Step 9: Multiple payment methods (ACH, PayPal, Amazon Payments)

Multiple payment methods are another way to provide your customers, new and otherwise, with all the payment options available, so that payments are frictionless. With Chargebee, the effort involved in setting up additional payment methods is mostly clerical. Simple configurations take the place of individual payment APIs.

Step 10: Tax Configuration

Tax regulations are evolving globally. In 2015, EU VAT became effective in 28 countries across Europe which resulted in new compliance requirements by all digital business trading with Europe, and not just incorporated in Europe.

In Australia, being able to provide "inclusive" vs. "exclusive" Tax Invoice is critical to ensure compliance.

In the US, there are thousands of combinations of taxes applicable based on state, city, county and sometimes different tax rates are applicable within the same zip code. As the business grows, it is important to have accurate tax calculation tools in place.

Chargebee provides two types of solutions for tax compliance requirements:

If you are familiar with taxes to be applied based on your country of incorporation and customer location, you may upload the tax rules into Chargebee as a CSV file.
To make tax compliance easier for countries with more complex tax laws (USA and Canada), we also integrate with Avalara, a certified tax assessor, to ensure accurate calculation of taxes. Like a payment gateway account, you would sign up for an account with Avalara and configure the details in Chargebee without having to do any direct integration with them.

Step 11: Integrating with other applications

Well aware of the myriad tools available to the digital merchant, Chargebee helps you be proactive about more than just your billing. It provides in-built integration via direct connect with solutions like Mailchimp, SalesForce, Quickbooks and Xero (upcoming), and DIY integration with services such as Zapier that allow you to build two-way integrations with hundreds of applications for a wide variety of use cases.

Step 12: Promotion Setup

Customer acquisition is likely the most challenging piece of the subscription puzzle and cannot be overcome without experimentation, creativity, and risk. Figuring out what works best for your business is hard - from the types of pricing iterations you need as you scale up to what kind of promotions you should offer new and existing customers and when, these decisions can make or break a digital merchant.

Take the example of a set of customers whose lifetime value is $2000 each. If your margins are about 50% to serve each customer, does it make sense to let your salesperson offer a 2-month, 50% discount applicable only on your $100 plan? What if your marketing team would like to personalize a country specific launch with an integration partner? Would you like to offer a free upgrade to your higher tier plan for 1 month, for all customers who have been with you over 6 months? A compelling feature-set might result in significantly higher revenue from the existing customer base.

Chargebee's Promotions module provides all the essential features you need to come up with promotions that work and implement them, tying all your subscription and invoicing data into elegant reports that can turn a data-fueled decision minefield into something you can engage with to bring your vision to life.

The lifecycle of a Subscription 

A subscription created against a plan is the beginning of a customer's association with your business. Our next section will map out the ‘lifecycle of a subscription' so you can understand documents generated at each stage, effectively use the billing system, and streamline your legal and internal operations.

Subscription events

A subscription changes as it moves through its lifecycle and we refer to these changes as "events". Here are some examples of events: active at end of trial, cancelled for non-payment, and renewed. Here are scenarios where changes to a subscription can trigger an event:

  • A customer has made a request for cancellation at the end of the current billing cycle. Since the cancellation was scheduled at the beginning of the billing cycle, there is no manual intervention required to cancel the subscription when it expires; the system automatically cancels the subscription without billing the customer again and triggers a cancellation event.

  • The system automatically cancels a subscription due to non-payment after repeated attempts to collect payment against an invoice.

  • A customer upgrades her subscription by including 3 additional users, effective immediately. This triggers an upgrade event and initiates an invoice for her with prorated charges applied.

These events provide an accurate snapshot of a specific change and the triggers that caused the change.

This information is useful for multiple purposes:

  • To synchronize with other systems like your web application or service whenever a change happens automatically or is initiated by your customer/internal team on behalf of the customer.
  • To keep track of all the changes to a living document like subscription and the associated changes and also to track history.


Chargebee sends notifications of events your way using Webhooks. Webhooks are designed to communicate with a specific web address and make sure the notification goes through.Your internet address/URL is securely configured in Chargebee so our webhooks can notify your system every time an event is triggered. This programmatic message is consumed at your end using what is called a "listener" program that can either act on the data being received, or simply record it. You can count on webhooks to be an authoritative source of information regarding your subscriptions and invoicing and to keep you system data in sync at all times; we've designed them to be reliable, factoring in every cause that might stop a notification from going through whether it is scheduled maintenence or server downtime.
Webhooks are built for the cloud - the robust mechanism will retry sending a failed notification until it receives an acknowledgement, even if it takes a few days. In the case of repeated failures even after several attempts, it is marked as a failure and it can still be triggered manually using the user interface.

Finance Operations - Invoicing and Credit Notes 

The finance operations aspect of subscription business is under appreciated in its complexity and finance teams usually bear the brunt as a business scales up. A streamlined system that takes care of complex proration logic, calculation of credits, creating credit notes, and accurate invoicing can counteract the many challenges a growing business will face when it comes to financing, substituting manual calculations and endless spreadsheets with automatically organized data.


An invoice defines the association between a customer and your product over time in the same way that a subscription defines the association between a customer and a plan. Fully customizable, it usually contains an itemized list of charges, including details of the customer's plan, additional add-ons, applicable taxes, discount line items, credits, and so on. Chargebee creates an invoice internally for all the applicable charges against your service/product for a customer.

When an invoice is created, the payment process is initiated and can be seen to closure internally (using stored payment details for automatic payment) or manually at a later time.


Chargebee can be used to generate beautifully formatted Tax Invoices that can be sent to customers on your company's behalf. Additionally, you can send tax invoices as legal documents. Remember to configure these features during your setup.

Credit Notes

A Credit Note is the near opposite of an invoice - it documents money that you owe the customer rather than charges owed to you. The most common reason to issue a Credit Note would be to refund a customer.

It's important to note that all credits needn't translate directly into cash refunds. Credit Notes are an opportunity to get creative with customer rewards.

Here are some examples of credits you might have to account for:
Cash Credits: Generated when a customer has overpaid and a certain amount needs to be refunded.
Adjustment Credits: Generated when a credit can be adjusted against your service/product and needn't be refunded as cash. For example, if you have provided $1000 USD service credit to entrepreneurs in your popular and exclusive ‘incubator plan', the amount is only available as service credit and should be refunded in cash when a customer cancels their account with you.
Promotional Credits: Generated to promote a product or to reward a customer, these credits resemble discounts and are applied before tax to reduce the total taxable amount (cash and adjustments credits, on the other hand, are applied after tax). Example: A referral bonus given to another customer.

Transactional emails

Of the numerous emails that a company sends out to its customers everyday some are personal and others, transactional. While personal emails need no explanation, transactional emails communicate commonplace details - receipts, password recovery, payment failures, card update notifications, and so on. They are routine and can use fixed templates with certain personalized and contextual information added (based on the specific data) to sound less perfunctory.

Here are some examples of transactional emails:

  • Payments related emails

    • Invoice Receipt - to send Tax Invoice.
    • Payment failure - sent for every automatic payment collection failure.
    • Expired card - sent after stored card is past the validity date.
    • Upcoming card expiry - sent 30 days before card expiry.
  • Subscription Lifecycle related emails

    • New subscription created
    • Upcoming subscription renewal (with configurable number of days to notify in advance)
    • Subscription canceled

Automating clusters of transactional emails with Chargebee can help you avoid manual work and guarantee prompt notification to the customer. Chargebee supports TEXT and HTML email formats and we advise setting up TEXT based emails as a backup for HTML content, just in case your customers aren't comfortable with HTML.

There are two other options available: Send these emails with your own SMTP configuration (which means you'd be using your own email hosting service and not ours) or send them using Chargebee's server.

Payment recovery

Dunning is the process of communicating with your customers for payment recovery in the event that a payment fails. In a recurring revenue business, where a customer's lifetime value is your first concern, payment recovery plays a crucial role in ensuring you don't lose a customer because of the failure of an automatic process. With card based payments on the rise, ensuring that you can recover failed payments quickly and efficiently, with a simple automatic retry, is increasingly important.

Your dunning management options with Chargebee are to

  • set up a rule engine for frequency of retry settings.
  • set up the pre-configured failure and success emails.
  • accurately track the unpaid vs. paid invoices at the organization and customer level.

With all of this complemented by webhooks and event notifications, you've got a powerful and failsafe process in place to automate payment recovery. Let your finance team handle the exceptions.

Changing subscriptions

Most of the changes that are made to a subscription are scheduled but a change can also be initiated by a customer or your team on a customer's behalf. To give you a picture of how a subscription can change, here is a subset of changes that can be initiated:

  • Transition from Trial to Active subscription
  • Transition from Trial to Cancelled
  • Upgrades or downgrades to a subscription
  • Transition from Future to Active subscription
  • Active to Cancelled due to non-payment

Managing Customer Trials

Many SaaS companies, in recognition of the value of a trial, require trial management tools and our trial management framework fits the bill perfectly. No matter how you want to adapt your trials (card vs. no card trials, paid vs. free trials vs. trials with setup fee, etc.), Chargebee has options that help you hit the ground running.

Subscription estimates

One of the key aspects of conversion is trust. And it starts with showing the customer that there are no hidden charges, being transparent about the pricing, and guiding them through every step of the way.

Chargebee's Estimate API allows you to calculate upcoming charges accurately for most transactional calls, before you would make the changes effective. This includes creation of new subscriptions, changes to a subscription, or even cancellation to accurately display immediate charges such as prorated charges, upcoming charges in the next billing, next billing date, etc.

Multiple subscriptions

Chargebee lets you create multiple subscriptions per customer.

We've made this possible by tying payment methods, billing information, and similar data to the customer rather than to the customer's subscription. With overarching data tied to the customer, and transactions and invoice data tied to a subscription, a customer has the freedom to subscribe to many things at once and you have the freedom to do the same on her behalf.

Customer self-service

As your business grows, handing over control to your customers provides the distinct advantage of gaining their trust and significantly reducing the effort that you have to put into customer service. Our customer portal allows you to let your customers manage their subscriptions including the payment information updates, personal detail updates, subscription and transaction history access, upgrade/downgrade options, and cancellation requests.

The customer portal comes with login management, hosted for secure access to customer data. Customers can access the portal using the email ID they've registered with you for availing your services. Chargebee also comes with single-sign-on capability to integrate into your own login system and let the customer through, based on the authentication at your end. This can be achieved using the SSO Login API.

The appearance of the hosted customer portal can be modified to match your website - Chargebee provides themes and also options to modify labels for the fields.

Of course, the option to sidestep our version of the portal remains open. If you prefer a complete in-app experience, we can help in two ways: take a look at how we've built our sample portal using the API as a reference for implementation and check out our open source version of the customer portal if you would rather implement one of the existing versions and build on it.

Importing existing data

Many startups choose to build an in-house billing solution on top of a payment gateway like Braintree or Stripe, which have basic subscription modules of their own. They manually handle use cases that fall out of the sphere of the gateway's module. The problem with this approach is that it requires constant maintenance, which gets harder and harder as the business grows. Billing is seen as an expense that can be mitigated with effort, rather than as an integral aspect of the business.

If this sounds familiar and you are looking for a way to take your billing forward in the next step of your operation, we provide a seamless way to transition billing information (while keeping and payment information just the way it is) by mapping existing tokens. This way you don't have to ask your customers for payment information again and you segue into a full-fledged billing system that can keep up with the growing needs of your business, all without any dedicated internal developer time. Not to mention the extended customer support team that would be available to advise your non-technical team on all billing related use cases.

Existing customer and subscriber information

In cases where subscription is managed by Stripe or Braintree we directly map the information from those systems into Chargebee. In case of bespoke billing systems, we would require export to an intermediate format before importing the data.

We recommend that you start accepting and managing new subscriptions with Chargebee, to ensure your data change is not a moving target. Once your billing workflow is set up to your satisfaction, and your existing data is stabilized, we will cleanse the data for accuracy and migrate it.

Existing transactional data

At the moment, we do not support migration of historical transactional data for the sheer complexity involved in pulling everything together. We do provide a DIY, CSV-based data import option which you could use.

Importing payment information

Chargebee supports data portability. If you want to transition out of our service, we've made it a priority to ensure that the process is hassle-free. Card information can be transferred out as required by the gateway you are using, or via an intermediate vault.

Note: If you are using Stripe or Braintree, we store card information directly in their respective vaults. In the case of these gateways, Chargebee maps critical payment information using tokens and will not change on the gateway's end if you stop using our service. In the case of other payment gateways we store card information in a third party vault and would request that you contact your payment gateway provider to help import the information directly into the vault, so that you remain PCI compliant.