Getting Started

Building Blocks

Custom Fields

Subscription Features

Localization

Invoices

Credits

Order Management

Billing Features

Taxes

Payment Methods

Direct Debit Payments

Configuring Gateways

Revenue Recovery

Hosted Pages

Notifications

Reports and Analytics

Data Privacy & Security

Fraud Management

Migration

Open Source Resources

Other Features

API Integration

Third Party Integrations

Addons 

Introduction 

Addons are a great way of selling additional products/services to your customers and boost your sales revenue. Chargebee helps you do just that.

Addons can be included in a Subscription while

  • creating the Subscription
  • changing/updating the Subscription
  • and additionally, for non-recurring addons, using the Add Addon action on the Customer or Subscription details page.

Creating an Addon 

To create an addon, navigate to Product Catalog > Addons > Create a New Addon and fill out the form.

Basic Addon Attributes 

Here we look at some essential attributes of an addon:

Addon name

The Name field must be defined for an addon. It is the name used to refer to the addon on the Chargebee user interface. It's good to have a name here that is descriptive of the attributes of the addon such as its pricing and period so you can easily distinguish it from other addons in your site.
So, instead of naming addons Addon A, Addon B etc., it makes more sense to name them "SMS Credits monthly USD", "Custom Reports quarterly AUD" etc.

Addon Id

The Chargebee API uses the unique addon id and not the Addon name to identify the addons that are on your website. An addon Id is the unique identifier of the addon and when a subscription is created or updated via the API from your app/website, the "Id" should be used to refer to the addon.

Invoice name

The invoice name field is used to define the name of the addon as it would appear to customers. This name is used for the addon in invoices, hosted checkout pages and the customer portal.
So, the invoice name for an addon should be that which you intend the customer to associate with the addon.

Note
If you don't set the invoice name, the addon name is used for it.

Addon description

Note
This is only shown on the change subscription screen for Portal v2.

A short description to the addon for the customer.

Type Attributes 

An addon can be recurring or non-recurring.

Recurring Addon

Such an addon renews each time the subscription renews.

Period
For recurring addons, you need to define a period. This is the period covered for the price of the addon. A recurring addon is only allowed to be attached to a subscription whose billing period is a multiple of the addon's period.

So, for example, the following statements hold:

  • An addon whose period is say, 2 months, cannot be associated with subscriptions with billing periods being an odd number of months.
  • An addon with a period of 1 year can be associated with a subscription of billing period say, 24 months.
  • Addons with week-based periods can only be associated with subscriptions with week-based billing periods.

The billing price of the addon would be the price of the addon multiplied by the number of addon periods that go into a single subscription period.

Example
Consider the following:
Plan billing period: 1 year
Plan price: $500
Addon period: 3 months
Addon price: $30
When the addon is signed-up for with the plan, we have the invoice as:
Plan cost: $500/year
Addon cost: $120/year ($30x4)
Total: $620

Note

As described above, the addon period does not determine when it is billed. In fact, addons get billed along with the subscription. The addon period is only used to calculate the billing price of the addon when attached to a subscription.

Non-recurring addon

A non-recurring addon or one-time addon does not get renewed. So it can be used for a one-off purchase such as extra data with an internet subscription. When such an addon is purchased in the middle of a subscription term, you may either choose to invoice it immediately or add to unbilled charges to be invoiced later.

Pricing Attributes 

Currency

Choose the currency that the addon will be billed in. If you do not see the desired currency listed, you may need to enable the currency in Chargebee. An addon cannot be attached to a plan with a different currency.

Note: You can only have one currency defined for an addon in Chargebee. If you wish to support multiple currencies for an addon, you must create separate addons for each currency.

Pricing model

The following options are available for addon pricing:

  1. Flat Fee
  2. Per Unit
  3. Volume
  4. Stairstep
  5. Tiered

1. Flat Fee
Flat Fee addons can be used for products/services that do not have a quantity associated with them. So it has a fixed price for the addon period.

Example
Along with a subscription for online storage if you sell "Premium Support", this would be a "Flat Fee" addon. There is no quantity associated with it.

2. Per Unit
Per unit priced addons can be used when products are charged per unit of quantity.

Example
You can sell anti-virus software (priced per device) as an addon.
The configuration would be:
Addon pricing: Per unit
Unit of measure: device
Price: $10
Charge type: Recurring
Period: 1 month
This addon would then be charged $10/device/month

3. Volume
Here too, the price is quantity-based. However, the per unit price is dependent on the range within which the total quantity falls. So under this model, you would define the quantity ranges and the per unit price for each. For example:

Tier 1 2 3 4
Units in tier 1-10 11-60 61-210 211 and above
Price $10/unit $7/unit $4/unit $1/unit

If a customer signs up for 100 units, they would be charged $4 per unit based on the third tier (61-210 units), for a total of 100 x $4 = $400.

4. Tiered
In tiered pricing also, the per unit prices are assigned to quantity-based ranges (tiers). When calculating the total price, quantities are purchased from successive tiers, starting from the lowest. Let's consider the same tiers as the example before:

Tier 1 2 3 4
Units in tier 1-10 11-60 61-210 211 and above
Price $10/unit $7/unit $4/unit $1/unit

If a customer buys 8 units, they would be charged $10/unit, which is $10 x 8 = $80.

If a customer buys 100 units then they would be charged:

  • $10/unit for the first 10 units (tier 1)
  • $7/unit for the next 50 units (tier 2)
  • $4/unit for the remaining 40 units (tier 3)

For a total of: $10 x 10 + $7 x 50 + $4 x 40 = $100 + $350 + $160 = $610.

On the web interface, the above examples for tiered and volume pricing are configured as shown:

See also:
How tiered pricing looks on Chargebee's Checkout and Self-serve Portal screens.

5. Stairstep

Stairstep pricing also defines quantity tiers against which prices are defined, but for each tier, a flat price is assigned instead of a per unit price.

So we have the following tiers or "steps" as before, with the prices against each as shown:

Steps 1 2 3 4
Units in step 1-10 11-60 61-210 211 and above
Price $75 $275 $500 $800

If a customer buys 100 units, they are charged as per step 3: a flat $500.
If the customer buys 5 units, they are charged as per step 1: a flat $75.
If they buy 400 units, they are charged $800 (step 4).

The configuration on the web interface is shown below:

See also

Examples on how proration is done for quantity-based pricing models when the quantity purchased is changed in the middle of a billing period.

Shipping Preference 

Note

This section is only available when Orders have been configured.

Allows you to configure whether the product is a physical item that can be shipped. If so, then for recurring addons, you must mention how often an item is shipped in a single addon period.

Accounting Fields 

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.

  • SKU: Store Keeping Unit or SKU is a name used to identify a product/service in inventory management or accounting systems. You can use this as an alternative name for your addon and it will be used as the Product Name in the accounting system.
  • 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: : . E.g. "Region: Northern"

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

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

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

Note
These fields will not be available by default, you should enable these fields at Settings > Configure Chargebee > Billing Rules and select Enable Accounting Fields for integration.

Taxes 

If Taxes have been configured, you can choose to exempt an addon from taxes by unchecking This plan is subject to taxes while creating the addon.

Tax Profile

If you are choosing to keep the addon taxable, choose a tax profile for it. This would determine — during invoicing — what taxes are applied to the price of the addon.

Self-serve Portal 

The Self-serve Portal can be used by your customers to make changes to their subscription. You can decide whether an addon is available to customers on the portal. This is done using the Display in Customer Portal checkbox while creating/editing the addon.

See also:
This FAQ for a glimpse of what tiered pricing looks like on the Self-serve Portal and Checkout.

Addon Actions 

When you are on the details page of any addon, you will find the actions pane on the right. The following actions are available:

Edit Addon

This allows you to change the addon configuration.

The Addon Id for an addon cannot be changed once the addon has been created.

If there are no subscriptions attached to the addon, then every attribute (except Addon Id) can be changed.

If subscriptions are attached to the addon then everything can be changed except the following:

  • Addon Id
  • Addon Charge Type (Recurring/Non-recurring)
  • Addon Period
  • Pricing Model
  • Currency
  • Tier/step prices (for volume, tiered and stairstep priced addons)
  • Shipping preference (only if order(s) has(have) been created for the plan)

Addon Price Change

When an addon has subscriptions attached to it, the price of the addon can be changed (though only when the addon pricing is flat fee or per unit).

Navigate to Product Catalog > [Addon name] > Edit Addon. Enter the new price of the addon under the Pricing section. Click on Update Addon.

The new price is applied to all new subscriptions with the addon. Existing subscriptions are not affected and continue to be renewed with the old addon price.

Clone Addon

You don't have to create an addon from scratch always. You can use the Clone Addon action to copy an existing addon and then make changes to it.

On clicking Clone Addon, a form just like Create a New Addon opens with the configuration of the cloned addon pre-filled. You can now edit the form and save to create the new addon.

Bulk Import of Addons

You can easily import a CSV file containing a list of add-ons into Chargebee. Chargebee allows you to import a maximum of 10,000 add-ons in a single shot.

To bulk import add-ons:

  • Click Product Catalog > Addons. The add-ons tab will open. This tab will contain the list of all the add-ons that you have created or imported.

  • Click the Import Addons button.

Step 1:

In the Upload CSV page that opens, upload the CSV file that contains the list of add-ons that are to be imported.

Note

Chargebee follows a naming convention to map the fields in the CSV to that in the application. Please make sure that your column names are specified as mentioned below.

  • Addon[id] - ID of the add-on
  • Addon[name] - Name of the add-on
  • Addon[invoice_name] - Invoice Name of the add-on
  • Addon[description] - Description for the add-on
  • Addon[charge_type] - Charge type of the add-on (ie. - recurring/non recurring)
  • Addon[price] - Price of the add-on
  • Addon[currency_code]- Currency code of the price (USD/INR etc)
  • Addon[period] - Tenure of the add-on (weekly/monthly/yearly)
  • Addon[period_unit] - Total period of the add-on (1,2,3)
  • Addon[type] - Type of the add-on (On Off/Quantity)
  • Addon[unit] - Total number of units
  • Addon[enabled_in_portal] - If it must be enabled in the customer portal or not
  • Addon[taxable] - If the add-on is taxable
  • Addon[tax_profile_id] - Tax profile ID
  • Addon[tax_code] - Tax code
  • Addon[invoice_notes] - Invoice Notes
  • Addon[meta_data] - JSON metadata (Refer this link)
  • Addon[sku] - SKU
  • Addon[status] - Status of the add-on (active, deleted etc)
  • Addon[accounting_code] - Ledger account code/name
  • Addon[accounting_category1] - Tracking category
  • Addon[accounting_category2] - Tracking category

Step 2:

Chargebee will validate the file and show the list of matched and unmatched columns. Unmatched columns are columns that have not followed Chargebee's rules for naming convention in a bulk update.

This step will contain 3 tabs:

Unmatched columns: Columns whose values could not be matched with the values in Chargebee

Columns matched based on the last operation preference: This section will contain the column names and the mapped columns, in case you have previously imported a CSV file. If this is the first time you are performing bulk operation for add-ons, you can ignore this section.

Matched columns: Columns whose value has been successfully matched with that of Chargebee's.

Match the columns accordingly and click Next.

Step 3: Confirm Errors

This step will display the errors that occurred while validating the file. Resolve the errors (if any) and then click Create Addons.

Note

Bulk operations are irreversible, therefore exercise extra caution while performing them.

Delete/Archive Addon

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

Deletion

  • An addon can only be deleted when it has no subscriptions linked to it. Once deleted, the addon is completely removed from Chargebee and it does not appear on the list of addons.
  • Once an addon is deleted, its name and Id can be reused.

Archiving

  • When you try to delete an addon that has subscriptions linked to it, it gets archived instead. This way the addon – though not deleted – is prevented from being used for new subscriptions.
  • Any existing subscriptions with the addon are not affected post archiving: they continue to renew as usual along with the subscription.
  • The name or Id of the addon cannot be reused when the addon is archived.

FAQ 

Can recurring addons be added to a subscription in the middle of its term?
Yes, this can be done by choosing Change Subscription under the list of actions available on the subscription details page. If proration is enabled, the charge for the addon is prorated for the remaining term of the subscription. If disabled, then the addon is charged for from the next renewal.

Can I control how many times a recurring addon renews with the subscription?
Yes, for this, enable billing cycle for addons.

How is a one-time charge different from a non-recurring addon?
A non-recurring addon is a product or service that has been modeled into Chargebee that does not renew with the subscription though it is linked to it. A one-time charge is an ad-hoc charge against a customer and is not linked to any particular subscription. More information about these two ways of charging is presented here.

I have a usage-based subscription model, how do I handle that in Chargebee?
Use Chargebee's metered billing feature to use non-recurring addons to apply usage charges.

Can I see how, say, an addon/plan with tiered pricing looks like on Chargebee Checkout and Self-serve Portal?

Yes, see this FAQ.

Was this article helpful?
Loading…