Integration Setup Guide 

This page is for a legacy version of the integration that maps Chargebee customers to contacts in Salesforce. The version was deprecated on 6th Jan 2020. If you have not migrated to the latest version (with account-based mapping), please contact support .


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

Unless otherwise specified, all changes made to the configuration are only applicable for newly synced records from the next sync onwards. Any previously synced records are not affected.


Case-sensitivity for comparisons

Whenever field values are compared between Chargebee and Salesforce to find matching records, the comparison is performed in a case-sensitive or case-insensitive manner depending on the property set for the field in Salesforce. Eg. Email addresses are compared in a case-insensitive manner.

Sync Date 

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

The date only applies to subscription, invoice and credit note records. Only those records created on or after the sync date 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 support  to change it.

Syncing Customer Records 

Data is synced between the customer object in Chargebee to account and contact objects in Salesforce. If person accounts are enabled in Salesforce, then data can be synced with them as well. Before a customer record in Chargebee can be synced with Salesforce, it must be mapped to an account and contact (or a person account) in Salesforce. The default mapping process is described in the following flowchart.


For the above flowchart:

We now look at sync configuration broadly and see what options are available.


Chargebee offers a great deal of flexibility when it comes to syncing customer records to Salesforce. This sections walks you through the options available.

As detailed in the flowchart above, for each new customer record, Chargebee looks up Salesforce contacts for a match. This is done by comparing the values of the unique ID field. This field is the email address by default. Contact support  if you wish to use a different field instead. Leads are looked up too if a matching contact is not found. However, matches among leads are only found using the email address field.

Duplicate matches
Ensure that multiple customer records in Chargebee do not have the same value for the unique field. Though this doesn't lead to sync errors, the integrity of the Salesforce contact data is affected as the latest changes from any matching record would be synced to Salesforce.


Skipping records
When the unique ID field is empty, the record fails to sync to Salesforce. You can use this to skip records from syncing: populate the unique ID field for a customer record once you know it should be synced to Salesforce. Remember that if lead lookup (explained next) is enabled for the integration, the email address field must also be left blank to guarantee that the record is skipped from syncing.

Lead Conversion

When no contact is found as a match, by default, Chargebee looks up lead records using the email address for a match. If found, it is converted as Closed-Converted. The account and contact (or person account) that result(s) from the conversion are (is) mapped to the Chargebee customer record.

Contact support  if you want Chargebee to…

  • not look-up leads at all.
  • or lookup and convert leads but…
    • 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)

Mapping an Account

The account that a customer record is mapped to is determined by the settings (highlighted in the screenshot below) found when setting up the integration for the first time. After first-time setup, they can be found under:

Apps > Go to Marketplace > Salesforce > Manage preferences > Sync Rules for Accounts

The following options are available under For customers in Chargebee with the same company name:

  • Create new contact and account: existing accounts are not looked up for a match and new accounts are created for every customer record. As described in the flowchart above, a new contact is only created if a match is not found.

Duplicate accounts
When choosing the above option, beware of Chargebee customer records with duplicate company name (described below) values. Duplicate records will not sync if Salesforce validation rules prevent duplication of account names.

  • Group under the same 'account' in Salesforce: the company name (described below) of the customer record is matched against the business account names in Salesforce. When a match is found, the customer record is mapped to that account.

What's the company name for a customer?

  1. It's the value of the company field, if available.
  2. If the company  field is empty, then it is the domain name of the email address.
  3. 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.

Person Accounts

If you are a business that sells to consumers, then you may be using person accounts in Salesforce. By default, Chargebee is configured to work with business accounts only. Contact support  to change this. You have the following options to choose from:

  1. Always use Business accounts. This is the default option and is used if you only sell to businesses.
  2. Always use Person accounts. This is good if you only sell to consumers.
  3. Use both Business and Person accounts.

How do I setup Chargebee to use person accounts?

  1. Enable person accounts in Salesforce. Use this guide  from Salesforce to see how.

  2. Contact Chargebee Support with the following information:

    • For options 2 and 3 above: the Salesforce record types that need to be set for person accounts and optionally, business accounts too.
    • For option 3 alone: Chargebee deems a given customer record as a business account when…
      • a. The company  field is populated.
      • b. Or a certain custom field is populated.

    Tell us which criteria (a or b) should be used and if you choose the latter, give us the API name of the Chargebee custom field.

Buttons for Person Accounts
Some Chargebee operations for contacts are applicable for person accounts. These are:

Normally, these buttons are only available for contacts. Since enabling them for accounts could confuse people working with business accounts, we only make them available upon request. Contact support  to enable them.

Opportunity Handling 

How Salesforce opportunities interact with Chargebee subscriptions can be configured in Chargebee.

Chargebee Quotes in Salesforce 

A quote in Chargebee is a document used to let a potential buyer know how much the goods or services will cost before they commit to the purchase.

Again, this setting is seen when setting up the integration for the first time. After first-time setup, it can be found under:

Apps > Go to Marketplace > Salesforce > Manage preferences

The following configuration options are available for Chargebee quotes in Salesforce:

Use Salesforce approval process for quotes

Enable this if you want the Send email operation for Chargebee quotes to be restricted until the quote is approved via a Salesforce approval process .

Attach a quote acceptance link in the emails sent from Salesforce

Enabling this option will include the quote acceptance link in the email body while composing it.

Field-level Customization 

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

Custom field-mapping 

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

Sync direction 

The sync for every pair of mapped fields happens in one direction only: either from Chargebee to Salesforce or the other way round. However, you can choose the direction you want the sync to happen for each pair of synced fields.

Skipping sync 

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 say, "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 Apps > Go to Marketplace > Salesforce. If the Auto sync toggle is enabled, the sync is automatically run every hour.

Other Considerations 


The currencies enabled in the Chargebee site(s) must also be enabled in Salesforce.

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 support  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, these features do not interoperate.
  • When a Chargebee invoice or credit note is synced to Salesforce, it is related to the contact that corresponds to the invoice owner in the Account Hierarchy 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?