Configuring Themes 

You can specify which fields are shown/required and also configure the labels and messages for the fields. Along with this, you can configure the themes to suit your look and feel.

To configure your hosted pages themes, go to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Themes in the web interface 

Chargebee comes with several themes for your hosted pages. You can customize these themes to match your website's look and feel and apply them to your hosted pages.

The themes are available in the Themes Gallery and you can pick, install, customize and publish the themes you need.

Select a theme and use the Install & Configure This Theme to install and customize the theme.

You can also download the themes and edit them as needed. After editing the theme, you can upload them in to your Chargebee site. Read more about editing the themes.

Configure Themes 

Using the theme editor, you can customize the look of your hosted page.

Some of the elements on the theme configuration page:

  1. Presets are pre-configured settings for your hosted pages. They can be edited and saved as custom presets that you can apply to your hosted pages when needed.
  2. Use the Preview option to see the changes you've made without saving them.
  3. Save and preview your changes using the Save button.
  4. Customize your hosted page here.
  5. See how the hosted page will look on different devices.

If you are making changes to your Published Theme, the changes are applied immediately to your hosted pages. If you're editing the theme configuration of an installed/uploaded theme, you can only see the changes after you've published it.

Building your own Chargebee Themes 

Find out what it takes to create a Chargebee theme and start customizing your checkout pages and self service portal to look the way you want them to be.

Chargebee's themes are built on top of Twitter's Bootstrap framework. No you don't need to master Bootstrap. It's quite easy and well documented.

Why Bootstrap?

The reasons why we picked Bootstrap to be the base for our themes are:

  1. Eco system - Bootstrap is a well known framework, widely used and has a large ecosystem of users.
  2. Save Time - The library offers ready made pieces of code and components to get you started immediately.
  3. Resources galore - There are numerous resources available on the web for Bootstrap.
  4. Responsive - Bootstrap's mobile first strategy ensures your checkout pages are mobile ready.

Who is this for?

  1. Are you a good web designer with HTML and CSS experience looking to build a theme from scratch? If yes, you are in the right place!
  2. Are you familiar with HTML and CSS but aren't confident enough in your skills to build a brand new theme from scratch? Consider downloading one of the themes from our Themes Gallery and try customizing it.

Chargebee's themes can be built easily with basic knowledge of HTML & CSS.

Things to know before building your own theme:

Mustache's templating language. See the documentation on mustache at .

Download and try editing the themes available in the gallery published by Chargebee.

Ensure your theme is customizable to suit your needs. You can add configuration meta information to generate the theme settings UI to easily configure the theme via the web interface.

Theme Structure 

The themes come in a zip file and contain the folder structure shown below. All the files are mandatory and should be present in the theme zip when uploading your themes.


For each hosted page - Checkout page, update card page there must be a template in the Templates folder. For example, for the Checkout page, there must be a template in the Templates folder with the name checkout.html.

The required files in the template folder are:

checkout.html - The page inside which the Checkout page for both plan specific hosted pages & API based checkout pages are rendered.

edit.html - The customer portal page which is used to render the edit page for account details, billing address, card details and shipping address. This page is also used to render the cancel subscription page.

error.html - The page which is rendered with the error message in case of errors while accessing the checkout page, update card page and customer portal pages.

iframe.html - The page inside which the both the checkout & update card page is rendered when requesting the hosted pages for embedding inside iframe within your app.

login.html - The page which is used to render the customer portal login page along with options to request reset password and sign up link.

portal.html - The customer portal page which is used to render the account details, billing address, card details, invoices, subscription details and shipping address for a customer.

thank_you.html - "Thank You" page shown after a checkout is successful. This is applicable for both plan specific hosted pages and hosted pages via API. You can also override this with your own redirect URL.

update_card.html - The page inside which the Update card page is rendered.


This holds the style sheets and images used in the CSS. Currently all the styles should go under the file css/theme.css.


This holds the configuration options for the theme.

meta.json - Configure all the options that can be modified for this theme from the web interface.

presets.json - Provide various color flavors and text for the themes.


Using the "Configure Theme" section provides an easy way to customize the look and feel of your hosted pages without having to deal with changing the HTML & CSS.

To build a theme customizable like this, you need to have the following things in place:

Have meta.json written in JSON format defining the elements that can be configurable for your themes without any development effort.

Have presets.json written in JSON format with default values for the various flavours(predefined styles) of the theme you want to provide.

Ensure the configuration settings defined in the meta.json are implemented in the theme.css and html files present under templates directory.

Changes made in the Configure Theme UI in the Chargebee's web interface is generated based on the configuration defined in the meta.json. Say you have a configuration defined as "body": {"background_color": {"data_type": "color","label": "Background color"}} and the value for this is mentioned in presets.json as #333333, this can be used as {{body.background_color}} in all the .css & .html files.

presets.json contains the preset value for the configuration defined in the meta.json. If the value for a specific preset configuration is not given, the value should be present in the defaults section. Otherwise you will get an error while uploading the theme.

Defining meta.json for your theme:

The meta section:

Meta section tells about the basic information of your theme.

Sample Code:

"meta": {

"checkout_layout": "two_column",

"theme_version": "1.6",

"meta_version": "1.1",

"bootstrap_version": "3.1.0"


Note: All the fields are mandatory.

theme_version - You can keep track of your theme updates using the version number.

bootstrap_version - The bootstrap version your theme is built on. Currently, Chargebee supports bootstrap version 3.1.0. The supported values are 3.1.0.

checkout_layout - The checkout layout to be used when you install this theme. The supported values are: flat, two_column and multi_step.

meta_version - This is the version used by Chargebee to track underlying meta or structure changes for themes. The current meta versions that are supported are 1.0 & 1.1.

meta_version=1.0 - This currently supports the hosted pages for checkout, update card, iFrame and error.

meta_version=1.1 - This includes supported pages on version 1.0 and also pages for the customer portal.

Configuration group:

You can group the various configuration settings logically so that it helps the users while configuring the themes via Chargebee's web interface. For eg., if you want to provide support to configure the favicon logo for the hosted pages, the configuration below should be the one that is used:

"header": {

"meta": {

"label": "Header",

"desc": "Configure your header section of your hosted pages"


"background_color": {

"data_type": "color",

"label": "Background color",

"desc": "Background color for the header section."


"use_logo": {

"data_type": "boolean",

"label": "Use brand logo",

"desc": "Whether to show your brand logo in the header. If no logo is added, just the header title will be displayed."


"logo": {

"data_type": "image",

"label": "Brand logo",

"desc": "A logo to identify your company, product or service to display in the header section."


"title": {

"data_type": "text",

"label": "Brand name",

"desc": "You can configure the title to be shown in the header section here. If a logo is present, the title will not be displayed"


"title_color": {

"data_type": "color",

"label": "Brand name text color",

"desc": "Text color for the title, if displayed."



Here "page" is the name of the group under which its settings will be grouped together. Each group has a meta section that holds information about that group.

label - Mandatory display name of the group section while showing it in the theme configuration UI.

desc - If provided, this will be the description for your group.

Define each configuration you want to support for that group

A configuration setting takes the following attributes:

data_type - The date type of the configuration. It could be one of

boolean - Shown as Radio buttons. Allowed values are true, false

color - Shown with a color picker. The value should be hex value starting with "#"

text - Shown a text field

textarea - Shown a text area

image - An image uploader is shown for the user to upload the image. The name of the image and it should be present under the assets/images directory.

label - The label of the setting in the theme configuration UI

desc - If provided, this will be the description for this setting.

You can have as many groups and as many configuration definition for a group.

Defining the presets.json for you themes:

presets.json carries the flavours for your theme you want to support. The configuration should contain at least one preset and the defaults section configured.

defaults section:

"defaults" : {




You can define the default values for the configuration to avoid providing the common setting values repeatedly for each preset. After defining the defaults, you can define as many presets for your theme.

"Fairy" : { }

Define the preset value for the defined configurations in the meta.json inside the preset configuration set.

Migrating themes to meta version 1.1 

If your current themes do not support the customer portal pages, you will not be able to enable the Customer Portal as it requires the latest version(meta_version=1.1) of Chargebee's themes.

To support the customer portal with the current themes, here's what you would need to do:

  1. If you have only installed and configured themes from Chargebee's theme gallery, you can re-install the latest version of the same theme from the gallery and configure it. The latest versions of the themes in the gallery supports the customer portal.
  2. If you've uploaded your own theme, you need to download your theme and implement the pages for supporting the customer portal. To do this, you can refer to one of our themes from the theme gallery and ensure that your CSS and HTML changes are ported over to your theme.

Here's what you need to do:

You need to add the pages login.html, portal.html and edit.html that are used for the customer portal to your theme.

Any new configurations you may have added to the meta.json & preset.json files should be supported in the new theme.

The theme.css with the customer portal specific styles should be ported over to your theme.css

Please write to us at support  for any help on migrating your current themes to support the customer portal.

Was this article helpful?