Opportunities & Subscriptions 

This page pertains to v1.37 of the Salesforce integration. If you last installed the Salesforce integration before 6th Jan 2020, it is likely that you are using a deprecated version of the integration (package v1.31 and below) that performs a contact-based mapping. To migrate to the current version, contact support .


Chargebee for Salesforce  offers an elaborate configuration for how opportunities in Salesforce interact with subscriptions in Chargebee. For the purpose of this integration, opportunities in Salesforce can be for:

  • creating a new subscription in Chargebee
  • changing (upgrading or downgrading) an existing one
  • renewing the term for a subscription that has a finite billing period.
    So, in time, a subscription can have multiple opportunities mapped to it, whereas an opportunity can be mapped to only one subscription at any given time.

Sales-driven vs Self-serve Approach 

The configuration for how opportunities and subscriptions work together has been designed keeping in mind that you may have a two kinds of workflows or a mix of both: a sales-driven approach or the self-serve approach.


This involves your sales team creating opportunities in Salesforce after converting leads or for existing accounts. Upon winning these opportunities, customer records and subscription would be created in Chargebee. In other words, the customer life-cycle is initiated in Salesforce before moving into Chargebee. The configurations under Setting 1 are intended for such scenarios.


Your business may involve your customers signing up for your products and services themselves. This way, their life-cycle with your business is not initiated in a CRM, like Salesforce and customer records and subscriptions are created directly in Chargebee. The configuration options under Setting 2 go along with such self-serve situations.

Of course, you may also have a hybrid approach where your customers have the option to manage their accounts themselves and are also engaged by your sales or customer success teams for upgrades etc.


To configure the settings, within Chargebee, go to Apps > Go to Marketplace > Sales & CRM > Salesforce > Manage preferences > Sync Rules for Opportunities. The following settings are available:


These settings are also shown when the integration is connected for the first time.

The settings seen here were updated on Nov 1, 2019. If your Salesforce integration was setup prior to that, then before making any changes to these new settings, contact support  to take stock of any backend configurations that you may already have set up with us.

1. When subscriptions are created from Salesforce 

Any changes to the settings here are effective in Salesforce only after the next sync.

The settings in this section are intended for a sales-driven workflow. In other words, they apply to such subscriptions that are created/changed from a Salesforce opportunity. These include:

  • If you create a subscription from within Salesforce but do not associate it with an opportunity, setting 2 applies.
  • Keep settings 1.1 and 1.2 disabled if you intend to manage opportunities from within Salesforce only and don't want Chargebee to make any changes to them.

1.1 Allow Chargebee to update the opportunity stage when a subscription is synced to Salesforce

(disabled by default)

If you send checkout links to your customers then you may want Chargebee to automatically update the stage of the opportunity once the customer has subscribed. Enable this setting to make that happen. The opportunity stage set here is determined by setting 3.

1.2 Update opportunity products in Salesforce with subscription's products in Chargebee.

(disabled by default)

Use this setting to update the opportunity products and price book to reflect the items in the subscription. Note that the opportunity products and price book are updated strictly as described here.

1.3 Allow Chargebee to automatically create/upgrade/renew subscription when an opportunity is won. (Beta)

(disabled by default)

This option automatically creates (when the opportunity is for a new subscription) or updates (when the opportunity is for an existing subscription) subscriptions in Chargebee when opportunities are "won" in Salesforce.

Once enabled, you can use the feature as follows:

  • Update the stage of an opportunity to one that is Closed with a 100% probability: such as closed-won.
  • Check the Update Chargebee checkbox for the opportunity. (It's a custom field introduced by Chargebee for opportunities.)
  • Immediately, a subscription creation or update operation is triggered in Chargebee for the opportunity. The details of the mechanism of this operation are given below:

Creating a subscription

A new subscription is created for opportunities for which products were added using Manage CB Products.


Before a new subscription can be created by this feature, among the contacts associated with the account, exactly one should have been synced with Chargebee. The subscription will be created against the Chargebee customer mapped to that contact.

A new subscription is created with the plan and addons that correspond to the opportunity products. The billing and shipping addresses in the account are automatically added to the subscription. It is recommended that the payment method be updated for the customer before attempting this operation or the operation will fail if the option to invoice immediately is chosen and auto-collection is on.

Updating a subscription

An existing subscription is updated for opportunities for which products were added using Manage CB Products and choosing Existing Subscription under Manage Products for.


The existing subscription status must be active, non-renewing or in-trial or this operation is not carried out.

The products of the subscription are replaced — via a change subscription operation — by those in the opportunity.

Updating a subscription from renewal opportunity


The existing subscription status must be active, non-renewing or this operation is not carried out.

A "renewal opportunity" is one that is created as described under setting 4.1 on this page. For such opportunities, the subscription is updated as follows:

1.3.1 Choose how you'd like to handle charges for subscriptions

This sub-setting determines whether the charges raised for the above action are invoiced immediately in Chargebee or added to unbilled charges.


Failure Logs
The above operation for creating or updating subscriptions could fail, say due to the following reasons:

  • Any of the validations discussed above fail.
  • Payment method is absent or has issues and auto-collection is "on" for the customer.
  • In case of renewal opportunities, the number of billing cycles for the plan chosen is "forever".
  • The country set in the Account billing or shipping address are not spelt the same as the allowed values in Chargebee.

Such failures are logged as a record in the CB Logs object in Salesforce with the opportunity ID and a description of the failure. Retries are not automatically attempted in case of failures so you must use the Create/Change Subscription operation to complete the failed actions manually.

2. When subscriptions are created directly in Chargebee 

If your customers sign-up for subscriptions themselves, without your intervention, subscriptions would be created in Chargebee by other means and not via Salesforce. Such subscriptions would have no opportunity mapped to them when they are created. The settings in this section apply to such subscriptions.


These settings also apply for those subscriptions that are created from an account or contact without choosing an opportunity.

2.1 When a subscription syncs from Chargebee for the first time

2.1.1 Always create a new opportunity (default)

A new opportunity is created and linked to the account mapped to the customer. The new opportunity is updated as follows:

  • The opportunity products and price book are set as described here.
  • The stage of the opportunity is set as per setting 3.
  • The opportunity is linked to the subscription so that one can be seen in the other's related list.

2.1.2 Update an existing opportunity

Under the account mapped to the customer, Chargebee looks for open opportunities that

  • are not linked to other subscriptions or quotes
  • also do not have checkout links sent for them

It then updates the last created of such opportunities as follows:

  • The opportunity products and price book are set as described here.
  • The stage of the opportunity is set as per setting 3.
  • The opportunity is linked to the subscription so that one can be seen in the other's related list. If there are no open opportunities

This setting appears only when option 2.1.2, is chosen. So under option 2.1.2, if no opportunities are found, you have the choice to either Create a new opportunity (as described above in 2.1.1) or Do nothing.

2.1.3 Sync subscription without opportunity lookup

Neither creates nor updates opportunities when a subscription syncs to Salesforce for the first time.

2.2 Allow Chargebee to sync In-Trial subscriptions to Salesforce

(disabled by default)

When enabled, the option chosen for setting 2.1 is also applied for subscriptions that are in-trial, including cancelled subscriptions that have been reactivated with a trial period. The opportunity stage for in-trial subscriptions is chosen via setting 3.2.

2.3 When a subscription is upgraded in Chargebee

You can decide what happens to opportunities when subscriptions are upgraded in Chargebee. A subscription is said to be upgraded when one or more of the following occur:

  • The plan amount has increased.
  • Any addon amount increases.
  • The total number of addons has increased.

This setting also applies when using the Change Subscription action in Salesforce.

The following options are available under this setting:

Create a new opportunity (default)

A new opportunity, linked to the same account as the customer, is created in Salesforce. Its opportunity products and price book are set as described here. The stage is set as per setting 3. You would use this option when you want to track every upgrade done in Chargebee as a full value opportunity in Salesforce.

Update existing opportunity

The opportunity to which the reference is found on the subscription is updated as described here and its stage is set as per setting 3. If no opportunity is linked to the subscription then nothing happens.

Do Nothing

No changes are made to the linked opportunity and neither is any new opportunity created.

3. Opportunity Stage for Subscription Creation 


These configurations are auxiliary ones for settings 1.1, 2.1 and 2.3 above.

3.1 Choose the stage you'd like to set the opportunity to

Set the opportunity stage for when opportunities in Salesforce are created/updated from subscriptions in Chargebee. This applies only when subscriptions are in active, non-renewing or paused status.

3.2 Choose the stage you'd like to set In-Trial subscriptions to

This is only applicable when setting 2.2 is enabled.

You may want the opportunities for in-trial subscriptions to be set to a different intermediate stage than the stage set for when they activate. Eg. you may have self-serve purchases where the subscription is in-trial when created in Chargebee. These customers may eventually update their payment method and their subscriptions will turn active. Chargebee in these cases can create an opportunity and keep it in an intermediate stage (say "Needs Analysis"). When the subscription turns active, it can move the opportunity to say, "Closed-Won".

4. Additional sync rules 

Any changes to the settings here are effective in Salesforce only after the next sync.

4.1 Allow Chargebee to create renewal opportunities for subscriptions with finite billing cycles (Beta)

Subscriptions can be termed. In other words, they can run for a finite number of billing cycles. When such subscriptions are near the end of their final billing cycle, your renewal sales teams would want to reach out to the customer for renewing the terms. Enable this feature to have Chargebee assist the renewal sales teams by automatically creating renewal opportunities for such subscriptions.

Once enabled, you must also configure the how often to run the Apex job to create the renewal opportunities. Do this as follows:

  1. Go to the Chargebee for Salesforce app.
  2. Click on the Chargebee Settings tab.
  3. Choose a frequency for running the jobs under Schedule Renewal Opportunity Jobs and click Schedule.

The Apex job does the following tasks when it runs:

The opportunity products and price book for the opportunities created/updated as part of the above-mentioned Apex job are updated as described here.

Performing a renewal

Once renewal opportunities have been created, you can open such an opportunity and carry out the renewal in two ways:


You can have the subscription contract renew itself automatically when the renewal opportunity is won. This is done via setting 1.3. Once the renewal is completed automatically, the opportunity reference field in the CB Subscription record is updated to this renewal opportunity.


On the opportunity, click on Create/Change Subscription and replace the No. Of Billing Cycles field with the appropriate value (change the value as: current value + the number of billing cycles for the renewed term).

4.2 When a subscription is cancelled

Choose what Chargebee does when a subscription is cancelled (whether in Chargebee directly or via Salesforce).

Update existing opportunity (default)

Updates the stage of the opportunity referenced by the CB Subscription record, to the setting specified. Nothing happens if no opportunity is referenced by the subscription.

Do Nothing

Do not perform any actions on opportunities when a subscription is cancelled.

How opportunities are updated from a subscription 

Whenever Chargebee updates an opportunity from its related subscription, the following actions are performed:

  • The opportunity price book is updated to the price book for the Chargebee site.
  • All the opportunity products are replaced with those that correspond to the recurring items in the subscription. As a limitation of the integration, the non-recurring items are not added to the opportunity. Let's look at an example:
  1. Consider that the subscription has the following products:

    • Plan: "Basic" ($100/month)
    • Set up fee: $250
    • Non-recurring addon: "Extra data" ($50)
    • Recurring addon: "Extra user" ($25/month)
  2. At this point, if a linked opportunity is updated from the subscription, the opportunity would have the following opportunity products after the update:

    • Plan: "Basic" ($100/month)
    • Recurring addon: "Extra user" ($25/month)
Was this article helpful?