Getting Started

Building Blocks

Subscription Features

Custom Fields




Order Management

Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Revenue Recovery


Self-Serve Portal


Reports and Analytics

Data Privacy & Security

Fraud Management


Other Features


Third Party Integrations

Salesforce: Integration Guide 

Flexibility is one of the greatest strengths of Salesforce and that's how you are able to effectively model your organization and its processes within Salesforce. Chargebee for Salesforce follows suit and offers a high level of adaptability to meet your workflows.

This page will help you understand what to look out for while setting up this integration and also see what configuration options are available for the integration and how to set them up.


On connecting multiple sites

If you are connecting multiple Chargebee sites to the same Salesforce org, the considerations discussed on this page apply to all of them.


Perform installation first

A lot of the customizations that the integration allows you to do can only be made once you have installed the Chargebee for Salesforce package in Salesforce. Finish the steps outlined in the installation guide and then return to this page to tune-up your integration.


Changes aren't applied retrospectively

All changes made to the configuration are only applicable for newly synced records from the point of applying the change. Any previously synced records are not affected.

Sync Date 

This date determines which records from Chargebee are synced to Salesforce.

The date only applies to subscription, invoice and credit note records. All such records created on or after the sync date only are synced to Salesforce. However, the integration syncs all customer records, plans, addons and coupons to Salesforce regardless of the sync date setting.


Once set, this date cannot be changed from the Chargebee UI. Contact  to change it.

Syncing Customer Records 

Customer records in Chargebee are synced to accounts and contacts in Salesforce. Moreover, customers are first checked against leads to find matches and convert them into contacts. Let's look at how this works and the customization options available.

Lead Conversion 

Whenever a new Chargebee customer record is to be synced into Salesforce, leads are looked up for a match – in a case-insensitive manner – using the email address field. If a match is found, the lead is converted as Closed Converted. Also, the contact thus created is linked to an account determined using the account matching process. No opportunity is created.

The above is the default behavior. Contact  if you want Chargebee to…

  • not convert leads and instead directly create/update contact and account records.
  • to find and convert leads but…
    • use a different lookup field instead of the email address to match customer records to leads.
    • set the converted lead status to something different from Closed Converted.
    • create an open opportunity upon conversion. (this option is good to use in tandem with behavior 2 option under setting 1.1 of opportunity handling)

Customer-Contact Mapping 

Whenever a new Chargebee customer record is to be synced into Salesforce, if no leads are found or if lead conversion by Chargebee has been disabled, the Salesforce contacts are looked up for a match:

A customer record in Chargebee is mapped to the contact with the same email address (compared in a case-insensitive manner). If no match is found, a new contact is created and mapped to the customer.

If you want Chargebee to match customer and contact records using a different field instead of the email address contact .


Duplicate matches
Ensure that multiple records in Chargebee do not have the same value for the field. Otherwise, the integrity of the contact data will be affected.


Skipping records
When the customer record field used to find a matching contact is empty, the record fails to sync to Salesforce. You can use this feature to keep records from syncing: populate the field for a customer record once you know it should be synced to Salesforce.

Customer-Account Mapping 

A customer record in Chargebee can be mapped to accounts in two ways.

Navigate to Settings > Third-party Integrations > Salesforce > Manage preferences and see the options under When a customer is created.


Fresh setup
If you are connecting the Chargebee site to Salesforce afresh or for the first time, these options will show up right after you have set the sync date.

Select this... And it means this...
Group using company name

The "company name" (described below) of the customer record is searched for in the Account Name field of the existing accounts in Salesforce.

If a match is found, the customer record is mapped to that account. Otherwise, a new account is created and mapped to the customer record.

In either case, the contact mapped to the customer record is linked to the mapped account.
Create new account for each customer

A new account is created in Salesforce for each customer record in Chargebee without checking the existing accounts.

(Remember that any validation rules in Salesforce against account name duplication may cause sync failures if one or more customer records in Chargebee have duplicate company names.)


What's the company name for a customer?

  • It's the value of the company  field, if available.
  • If the company field is empty, then it is the domain name of the email address.
  • However, if the email address domain belongs to well-known ISPs or email service providers, the company name is the value of the id  field of the customer.

Opportunity Handling 

Subscription-Opportunity Mapping 

The second and third settings in the screenshot above determine how opportunities are created/updated via the integration. The table below explains the options:

For the setting... When you choose... Here's what happens...

1. When a subscription is created

(This setting is not applicable when an opportunity is selected while invoking the Create Subscription action from within Salesforce.)

This option either creates a new opportunity or updates an existing one. The detailed mechanism is as follows:

The subscription is synced to a new record in the CB Subscription object.

As for creating opportunities, two options are available:

Behavior 1 (default):

Create a new opportunity for the subscription, even if there are existing open opportunities. The opportunity stage is set as described in the table below this one.

Behavior 2: (contact to set this)

Under the account, Chargebee looks for open opportunities with either no price book or the price book for the Chargebee site the subscription belongs to. It then takes the last created of such opportunities and updates it. If it doesn't find any such opportunities, a new one is created.  The opportunity stage is set as described in the table below this one.

Use behavior 2 when you have enabled open opportunity creation upon lead conversion.

2. Do not create equivalent opportunities

The subscription is synced to a new record in the CB Subscription object.

No opportunities are created or modified on subscription creation.

3. Do not create opportunities only for trial subscriptions Same as option 1, except that no opportunities are created when the subscription is in trial . However, when the subscription goes active, an opportunity is created or updated as discussed for option 1. 

2. When a subscription is updated.

(Includes trial activations)

1. Update existing opportunity

The CB Subscription record for the subscription is updated.

The opportunity attributes (including any opportunity products associated with the opportunity) are changed or updated to reflect the changes in subscription.

2. Create new opportunity for full value

The CB Subscription record for the subscription is updated.

A new opportunity is created for the changed subscription. No previously created opportunities are modified. 

The opportunity stage set for each kind of subscription status is shown below. Some of the stage field values can be altered from the backend.

If the subscription status is... The opportunity stage is set as....
active, non-renewing or paused Closed Won
in trial

Closed Won

(Contact to set a different value.)


Closed Lost

(Contact to set a different value.)


No opportunity is created.

Field-level Customization 

This sections explains what field-level customizations can be added as part of the integration. Contact  or your Sales or Customer Success rep to set them up.

Custom field-mapping 

Chargebee allows you to define additional field-mapping over and above the standard field-map. You can map standard or custom fields in Salesforce objects to standard or custom fields in a Chargebee object.

  • The mapping is directional, which means that you must also specify in which direction the field values are copied: whether from Chargebee to Salesforce, or the other way around. You cannot also set the same pair of fields to sync the other way.
  • Custom mapping overrides any standard mapping that it may conflict with.

Skipping sync for some fields 

Any non-mandatory fields in Salesforce can also be skipped from the sync process. No data is synced between Chargebee and Salesforce for such fields.

Tagging records modified by Chargebee 

There is also the provision to pass a constant value to any field in Salesforce. This can be useful if you wish to tag object records modified or created by Chargebee.


You can define a field named "Source" in the Contact object and have us configure the integration to populate it with the value "Chargebee" for all contacts created or updated by Chargebee.

Mandatory Fields 

Fields in Chargebee that sync to mandatory fields in Salesforce must always be populated with values, failing which, sync errors would occur.


Last name
The Last Name field is mandatory for a contact in Salesforce. If this field value is absent in Chargebee, an underscore ( _ ) is inserted when the field is synced to a contact.

Auto Sync 

Once the integration has been setup, by default, the sync runs only manually using the Sync now button available under Settings > Third-party Integrations > Salesforce. If the Auto sync toggle is enabled, the sync is automatically run every hour.

Other Configurations and Requirements 


  • If multicurrency is enabled in Chargebee, then it must be enabled in Salesforce and all the currencies enabled in the Chargebee site(s) should also be enabled in Salesforce.
  • If multicurrency is not enabled in both Chargebee and Salesforce, their currencies must match.

Data Validation 

If you use picklists for fields in Salesforce then there are chances of sync errors if the Chargebee data flowing in, does not conform to the picklist options.


Say a field country is a picklist in Salesforce with "United States" as an option. If the data coming in from the mapped Chargebee field happens to be "USA", it results in a sync error.

It is recommended that you:

  • either ensure the synced fields on the Salesforce side are text fields and not picklists.
  • or, if the Salesforce-side field is a picklist and the Chargebee-side field is a custom field, then see if the latter can be made into a dropdown custom field.

Record Type 

If you need us to set a Record Type for your objects, then contact and give us the value for the Record Type Name field that should be passed into the synced records by Chargebee.

Considerations when using Account Hierarchy 

  • Account Hierarchy as a feature exists separately in both Salesforce  and Chargebee.
  • However, account relationships are not synced between them via the integration.
  • Whenever a subscription, invoice or credit note is synced to Salesforce, the contact to which it is linked is as per the account hierarchy configured in Chargebee. For example, if say, Yashiro from Acme-Asia is invoiced for all charges incurred by Kumar from Acme-India, then though a subscription shows up as related to the contact Kumar, the invoice for it (and any credit notes) would be related to the contact Yashiro.
  • Also see notes under the following Chargebee actions in Salesforce:

Was this article helpful?