How to map an addon/charge to a plan?

Modified on: Mon, 12 Dec, 2022 at 5:01 PM


What are the events the recurring addon is added to a subscription?

List of events the charge/non-recurring add-ons are attached to a subscription?

How to add applicable add-ons and charges in PC 1.0?

Unable to attach an addon to a plan

Plan - addon association


Primarily, Addons (PC 2.0) & Recurring addons (PC 1.0) are recurring entities, hence they can be added as Mandatory, Recommended, or Optional until the billing period of an addon with the subscriptionHowever, Charges (PC 2.0) & Non-recurring addon (PC 1.0) are non-recurring entities and they are added as per the events based such as Subscription creation, Subscription trial start, Plan activation, Subscription activation, Immediate, Contract termination, or On Demand.


Attaching Addons/Recurring addon:

In the Attach an addon popup, select the addon that you want to attach to this plan from the drop-down and select an applicable option:

To add applicable addons and charges to a plan, follow these steps:


  • When set as mandatory, the addon is automatically attached to new plan activations and cannot be removed (except via API) and the quantity cannot be edited either.
  • If a subscription changes to another plan where the addon is not mandatory, the addon is removed from it automatically.


  • When you set an addon as recommended in the Chargebee app, the addon is suggested in the Checkout and Portal to the customer, when you have enabled the recommended addon setting for Checkout and Portal.
    • In the API, the attachment type attribute for the addon in the plan resource is set to recommend. You can then use this information to implement add-on recommendations on your custom-built website/application.

Optional (Only available when addons are restricted)

  • Designating an addon as optional allows it to be attached to the subscription optionally.

Attaching Charges/Non-recurring addon:

 In the Attach a charge popup, select the charge that you want to attach to this plan from the drop down and select an applicable option and save.

  • Subscription creation: When a new subscription is created in Chargebee. Note that if a subscription is created today and set to start in the future, the subscription creation event is considered to have happened today.

  • Subscription trial start: For plans with trials, the time when the trial starts for the customer. For example, if you want to charge your customers a fee for the trial period, you can create a non-recurring addon for it and set it for a plan to be charged on the subscription trial start.

  • Plan activation: This includes all cases under subscription activation and the case when the subscription undergoes a plan change. For example, assume a plan ABC with a non-recurring addon Activation fee attached to it, set to be charged on plan activation. If the plan of a subscription is changed from any other to ABC, this addon would be immediately applied to the subscription. Now, if the plan is again changed to another plan and then switched back to ABC, the addon is only applied if the Apply charges option for it is set to Every time this event occurs in the details page for ABC.

  • Subscription activation: Whenever the subscription status goes active. This includes reactivations. Choose the Apply charges option Every time this event occurs if you wish to include the addon during subscription reactivations.

  • Immediately: Choose this option if you want the charge to be effective immediately.

  • Contract termination: This option appears when you have contract terms enabled on your site. When you attach a charge using this condition, then the charge will be implemented when the contract termination action is completed for that subscription.

  • On-demand: (Only available when charges are restricted): This allows the charge to be attached to a subscription for the plan, at any time. However, this option is available (and required) only when you select specific addons and charges to be applicable for the plan in step 2. When you select all addons and charges to be applicable, you can attach any charge to the subscriptions of the plan at any time.

The addon and charge attachment happens at a plan level, and any new price point that is added automatically inherits the applicability and conditions without any manual intervention.

Configuring Applicable addons in PC 1.0

Navigate to the details page of a plan > Scroll to the section titled Addons > Choose the settings:

You can either allow all addons to be applicable to the plan or click on Manage to restrict them to a few or none.

Classic UI users (PC 1.0)

Here's how the screen appears in Classic UI:

Configuring Applicable Addons and Charges in PC 2.0

To add applicable addons and charges to a plan, follow these steps:

  1. Click Product Catalog > Plans. Select the plan for which you are adding applicable addons and charges.

  2. On the Plan details page, scroll to the Applicable Addons and Charges section. All addons and charges are set as applicable by default. You can click Change and select specific addons and charges to be applicable.

  3. Click +Attach and select Addons or Charges from the drop-down.

  4. Attaching Addons: In the Attach an addon popup, select the addon that you want to attach to this plan from the drop-down and select an applicable option.

Viewing Addons and Charges Association

The addon and charges association with a plan can be viewed in the following places in Chargebee.

Plan Details Page

All the applicable addons for a particular plan can be seen on the details page of the plan.

Addon Details Page

Similarly, the details page for an addon or a charge shows the plans that it is associated with.

Here’s a table on  how the Addons and Plans can be associated:

Plan - Addon Association



Monthly Plan

Monthly Addon

Quarterly Plan

Monthly Addon 

Quarterly Addon

Half-Yearly Plan

Monthly Addon 

Quarterly Addon

Half- Yearly Addon

Annual Plan

Monthly Addon 

Quarterly Addon

Half- Yearly Addon

Annual Addon

After an addon is attached to a plan as recommended or optional, it can be added to any of its pre-existing subscriptions via the change subscription action.
For gift plans, you can only associate charges on-demand. Event based applications are not possible.
The add addon action at the customer level can be used to add any charge regardless of how addon applicability is configured.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.