Getting Started

Product Catalog

Customers

Subscriptions

Invoices, Credit Notes and Quotes

Taxes

Payments

Site Configuration

Data Privacy & Security

Data Operations

Reports and Analytics

Integrations

Integration Setup Guide 

Important
If you have setup the Salesforce integration before 27th July 2020, it is likely that you are using an older version of the integration. To migrate to the current version, contact [email protected] .

Introduction 

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

This page will help you understand the configuration options that are available for the integration and how to set them up.

Note

On connecting multiple sites: If you are connecting multiple Chargebee sites to the same Salesforce organization, the considerations discussed in this page is applicable to all the sites.

Changes aren't applied retrospectively: Unless otherwise specified, the changes made to the configuration are applicable only for newly synced records. The new set of configurations are applied in the next sync after the change. 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. Chargebee ID and Salesforce ID are case sensitive, while the rest are not.

Syncing Customer Records 

Customer records in Chargebee are mapped and synced to accounts in Salesforce. The mapping is one-to-one, which means that any given customer or account record cannot participate in more than one customer-account relationship (including Person accounts.)

Note

Chargebee - Salesforce Integration follows a 1:1 mapping. This means that a customer in Chargebee can be linked to only 1 account in Salesforce. The condition remains true even if multiple Chargebee sites are connected to Salesforce.

The data is synced in a bi-directional manner. That is, the information can flow from:

  • Chargebee to Salesforce
  • Salesforce to Chargebee

Chargebee to Salesforce (Self-Serve) 

In the self-serve model, the customers land on your website and sign-up for the subscriptions themselves. In such cases, the customer and their subscription information is created in Chargebee directly. The integration pulls data from Chargebee into Salesforce. You can choose to run this manually or automatically.

Salesforce to Chargebee (Sales-Driven) 

If you have a sales-driven model, your sales team starts the cycle in Salesforce. They work through the opportunities or accounts in Salesforce and create Chargebee customers and subscriptions from them. Data is pushed from Salesforce to Chargebee according to the field mapping.

Prerequisites 

Configuring v1.38 and above, requires you to complete the following prerequisites:

My Domain registration 

My Domain gives you a point-and-click way to brand the page that prompts users to log in to your Salesforce organization. Learn more

To add a domain, follow the below steps:

  1. Search for My Domain in the Quick Find box from Setup and select it.

  2. Click Add a Domain.

  3. Enter the domain name and click Check Availability.

  4. Click Register Domain. You will receive an email once the domain is registered.

  5. Once you receive the email deploy it to your users.

Enable Chargebee Integration tab 

Note

This option will be available only if you have installed the package. Refer to our installation guide to learn more.

Enabling the Chargebee Integration tab is necessary to configure the integration settings.

To do this, follow the below steps:

  1. Search for Profiles in the Quick Find box from Setup and select the System Administrator profile.

  2. Click Edit and change the Chargebee Integration setting from Tab Hidden to Default on.

Assigning Permission Sets 

Note

This option will be available only if you have installed the package. Refer to our installation guide to learn more.

Only the users added in this step will be able to setup the integration.

To add a user:

  1. Search for Permission Sets in the Quick Find box from Setup.

  2. Select Chargebee for Salesforce Admin User

  3. Click Manage Assignments and add your users.

Configuration 

To integrate Chargebee with Salesforce, you need to initiate the package installation from Chargebee.

Once you have installed the package, you will be redirected to log into your Salesforce account.

You can now configure the settings from Salesforce.

In Salesforce 

Step 1: Get Started 

Once you log into your account in Salesforce, you are taken to the Getting Started screen. If not, navigate to the App Launcher and search for Chargebee Integration.

Whitelisting

It is necessary to set up a remote site to whitelist your Chargebee site in Salesforce. To do this:

  1. Search for Remote Site Settings in the Quick Find box and click New Remote Site.

  2. Add the URL of your Chargebee's site. (Example: https://acme-test.chargebee.com)

Click Get Started.

Step 2: Enter Domain 

  1. Enter your Chargebee Domain ID. (Example: https://acme-test.chargebee.com)
  2. Create an API Key with full access in Chargebee and enter it in the API Key section. Here's how you can get an API key. Click Connect.
Note

It is recommended that you create a separate API key for Salesforce.

Step 3: Sync Rules 

These settings determine how customers and subscriptions in Chargebee map or interact with the custom and standard objects in Salesforce such as accounts and opportunities. In case you do not configure these settings, the default options will be considered. You can edit the settings any time.

Sync rules for Accounts (Self-Serve model)

These settings determine how customers that are directly created in Chargebee sync to Salesforce. The rules mentioned in this section govern how the customer data syncs with Salesforce during different scenarios.

1. Select customers to sync

This setting applies to only those customer records that have never been synced to Salesforce. Available options are:

a. Sync all customers - All customer records in Chargebee are synced to Salesforce.

b. Sync only customers with subscriptions - Only those customer records that have at least one subscription are synced to Salesforce.

2. Choose a unique field to identify and map customers from Chargebee to accounts in Salesforce

Here you choose the field in Chargebee (on the left) and Salesforce (on the right) that are used to find matches between customer records in Chargebee and accounts in Salesforce.

This setting only determines the pair of fields used to find matches. It does not alter the field-mapping for actual data sync in any way.

The available fields are as follows:

Fields available in Chargebee:

  • Customer ID
  • Phone
  • Email
  • Company
  • Any other String or Number data type custom fields configured in the Chargebee customer module.

Fields available for Accounts Object in Salesforce:
All standard and custom fields on the Salesforce account of type string or number are available for selection. Custom fields created by Chargebee on the Salesforce account such as Chargebee email, Chargebee first name, Chargebee last name, Chargebee customer ID etc are not supported.

It is recommended that you choose a pair of fields that are unique. Avoid using company names to match the records as any difference due to data entry/typos (For example: ‘Acme Inc' in Chargebee and ‘Acme Inc.' in Salesforce) affects the mapping.

Fields available for Contacts Object in Salesforce:
All standard and custom fields on the Salesforce account of type string or number are available for selection. Custom fields created by Chargebee on the Salesforce account such as Chargebee email, Chargebee first name, Chargebee last name, Chargebee customer ID etc are not supported.

Note

On skipping records
If the email field is populated for a Chargebee customer, then it searches and attempts to convert a matching lead, provided the lead conversion setting is turned on. You can leave the field empty to skip records from syncing and populate the field for a customer record once you know it should be synced to Salesforce. Remember that if lead lookup is enabled for the integration, the email address field must also be left blank to guarantee that the record is skipped from syncing.

Note

When a Chargebee customer record is to be synced to Salesforce:

  • The contacts are looked up to find a match.

  • If a match is found and if that contact is attached to an account, then the latter is deemed as the mapped account and action is taken as per 'Choose what happens when a customer in Chargebee has a matching ‘account' in Salesforce' setting.

  • If a contact is not found in step 1 or no account is found to be attached at step 2, the account is deemed to be not found and action is taken as per Choose what happens when a customer in Chargebee does not have a matching ‘account' in Salesforce setting.

3. When a Chargebee customer has a matching account in Salesforce

a. Overwrite with Chargebee data: Push data to all standard fields on the account that are part of the standard field mapping.

b. Overwrite empty Salesforce Fields: Push data only to those Standard fields (that are part of the field map) in Salesforce accounts that are empty.

c. Map only: Do not push any data to fields in Salesforce accounts. This setting is useful if you want to establish a link between the Chargebee customer and Salesforce account without field level data interchange.

4. When a Chargebee customer does not have a matching account in Salesforce

When the sync runs, it is possible that account matches are not found for certain customer records. This setting determines the behavior for such conditions. Available options are:

  • Find and convert leads to accounts
  • Always create 'account' in Salesforce
  • Do nothing

a. Find and convert 'leads' to account: Chargebee looks up lead records using the email address for a match. The account that results from the conversion is mapped to the Chargebee customer record.

Enable the option "Allow Chargebee to create opportunity in Salesforce when converting leads", if you want to create opportunities in Salesforce.

Next, select the stage that the leads must be converted to.

When a Chargebee customer does not have a matching lead in Salesforce: Select the action to be performed when Chargebee customer does not have a matching lead in Salesforce.

Available options are:

  • Always create 'account' in Salesforce
  • Do nothing

b. Always create 'account' in Salesforce: Create a new account in Salesforce and sync data to it as per setting 3 (When a Chargebee customer has a matching account in Salesforce). If you select this option, you can choose to Allow Chargebee to create contacts for accounts in Salesforce by enabling the toggle highlighted in the image below.

c. Do nothing: Does not do anything.

Note

Duplicate accounts: When choosing this option, beware of Chargebee customer records with duplicate values for the field chosen in setting 2. Duplicate records do not sync if Salesforce validation rules prevent duplication of account names. We recommend that you setup your processes and automation such that only unique customer records are maintained in Chargebee to prevent issues with integrations.

5. Allow Chargebee to create contacts for Accounts in Salesforce: Enable the toggle if you want to allow Chargebee to create a contact for accounts in Salesforce. However, changes made to a customer in Chargebee will not be automatically updated to the contact in Salesforce

Next, choose the kind of account that you have in Salesforce. Available options are Business account, Person account, and Both. The option to select Person account or Both will be displayed only if Person accounts are enabled, or if a different record type for accounts is configured in Salesforce. This setting will not be visible, if otherwise.

Person Accounts

If you are a business that sells to consumers, then you may be using person accounts in Salesforce. Enable person accounts in Salesforce. Use this guide  from Salesforce to see how.

a. Under Choose the kind of accounts you use in Salesforce, select any one of the following:

  • Business Accounts: This is the default option and is used if you only sell to businesses.
  • Person Accounts: This is good if you only sell to consumers.
  • Both: In case you select Both, then you need to specify when Salesforce should create a Person Account. Please note that this option would be visible only if you have enabled Person accounts.

b. Select a record type under Choose the person record type and Choose the business record type.

c. For person accounts, select an option under Choose how Salesforce should create a Person Account:

  • Always
  • Never
  • Based on Company field on Chargebee customer: Chargebee creates a business account when the Company field of the Chargebee customer record is populated. If the Company field is empty, a person account is created.
  • Based on Custom field on Chargebee Customer: Chargebee creates a business account when a custom field in Chargebee is populated. Select the custom field to be used. If the field is not populated, a person account is created.

6. Select the custom fields that you want to sync from Chargebee to Salesforce

Please note that custom fields can sync only in one direction. This means that you should not choose the same pair of fields selected here for setting 7.

7. Select the custom fields that you want to sync from Salesforce to Chargebee
Please note that custom fields can sync only in one direction. This means that you should not choose the same pair of fields selected in setting 6.

8. Default mapping

If you have certain mandatory fields configured for Salesforce objects such as accounts and/or contacts, specify default values for them here so that the integration does not run into errors when attempting to create them.

Sync Rules for Opportunities 

These settings determine how subscriptions created or updated directly in Chargebee or via the integration from Salesforce, interact with opportunities in Salesforce under various conditions.

When subscriptions are created from Chargebee 

If you have a self serve model where customers purchase subscriptions or sign up for a free trial directly via your website, then subscriptions are created in Chargebee first. Alternately, you may have a sales model where the sales team creates opportunities in Salesforce, but subscriptions are created by the finance or operations team directly in Chargebee. In this section, we are going to see the settings that one needs to configure to determine how these subscriptions map to or create opportunities in Salesforce.

1. When a subscription syncs from Chargebee for the first time: Select an option to determine what the integration does when a subscription syncs from Chargebee for the first time. The available options are:

  • Create New,
  • Map Existing
  • Do not create

a. Create New: Use this option to create a new opportunity in Salesforce. You need to specify the stage to be set for the newly created opportunity.
Selecting this option updates the stage, opportunity products and price book. And, the subscription has a lookup relationship to the opportunity.

The new opportunity is updated as follows:

  • The opportunity products and price book are set as described here.
  • The stage of the opportunity is updated as selected.
  • The subscription is updated with a lookup field to the opportunity.

b. Map Existing: Under the account mapped to the customer, Chargebee looks for open opportunities that

  • are not linked to other subscriptions or quotes
  • 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 updated.
  • The opportunity is linked to the subscription so that one can be seen in the other's related list.

When you select map existing, Salesforce will check for an existing opportunity for the subscription and map with it. You need to specify the action to perform in case there is no existing opportunity. Available options are Create New, and Do Nothing. If you select Create New, then specify the stage to set to the opportunity. If you select Do nothing, then it does not update anything.

c. Do Nothing: Does not update anything in Salesforce. While this does not update any opportunity or create a new one, it does sync the subscription itself.

2. Trial Subscription: Enable this option if you want to create opportunities for subscriptions that are in trial including canceled subscriptions that have been reactivated with a trial period.

Assign a stage that should be set for the opportunity for in-trial subscription. Note that this is different from stage set for subscriptions that are not in-trial.

3. Subscription Upgrades: Choose how you want to handle the opportunity related to a subscription that is 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.

Available options are: Create New, Update Existing, Do nothing.

The following options are available under this setting:

a. Create a new opportunity

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. You can use this option when you want to track every upgrade done in Chargebee as a full value opportunity in Salesforce.

b. 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.

c. Do Nothing

No change is made to the linked opportunity nor is a new opportunity created.

4. Subscription Cancelations: Choose how you want to handle opportunities when a subscription is canceled in Chargebee. Available options are Update Existing and Do nothing. If you choose to update an existing opportunity, select the stage.

5. Additional Field Mapping: Select the Custom fields to sync from Chargebee to Salesforce. You can map the standard or custom fields in Salesforce objects to the standard or custom fields in a Chargebee object.

When subscriptions are created from Salesforce 

In this section, we describe the settings that determine how subscriptions that are created from a Salesforce opportunity interact with that opportunity. These settings apply if you have a sales model where all your subscriptions are directly created from Salesforce opportunities.

1. Allow Chargebee to update the opportunity stage when a subscription is synced to Salesforce:
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. On enabling this, Chargebee will be able to move the opportunity to the selected stage once the customer makes the payment.

2. Allow Chargebee to update the opportunity products in Salesforce with subscription's products in Chargebee: Enable this if you want to override the products added in the Opportunity with those in Chargebee's subscription.

3. Allow Chargebee to automatically create/upgrade/renew subscription when an opportunity is won (Beta): 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. (‘Update Chargebee' is a custom field introduced by Chargebee on the opportunity object.)

  • 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:

a. Creating a subscription

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

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.

b. 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.

Note

Validations
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

Note

Validations
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 Allow Chargebee to create renewal opportunities for subscriptions with finite billing cycles (Beta). For such opportunities, the subscription is updated as follows:

Example

If the renewal happens when the subscription has 2 billing cycles remaining and if the billing cycles defined for the plan at this point is 5, then on renewal, the subscription would have 2 + 5 = 7 billing cycles remaining.

4. Additional Field Mapping: Choose the custom field sync from Salesforce opportunity to Chargebee subscription.

Information

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

Renewal Opportunities 

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 sync. Available options are Daily, and Weekly.
During the sync:

  • It creates renewal opportunities for all active and non-renewing subscriptions that meet both of the following criteria:

    • the subscription has finite number of billing cycles.

    • the subscription plan has finite number of billing cycles.

  • For existing renewal opportunities, it updates the opportunity products and price book from the subscription. This ensures that if the subscription was upgraded or changed during its term, the renewal opportunity's products is updated.

Performing a renewal 

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

Automatic:

You can have the subscription renew itself automatically when the renewal opportunity is won. This is done via the option Allow Chargebee to automatically create/upgrade/renew subscription when an opportunity is won. (Beta). Once the renewal is completed, the opportunity reference field in the CB Subscription record is updated to this renewal opportunity.

Manual:

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).

Additional subscription settings 

Specify default override values for mandatory fields in Salesforce.

Allow one time and limited period coupons to be used in opportunity product discount calculations: Enable this option if you want to include limited and one time coupons in the discount calculations. This setting impacts the ‘discount' field on the ‘Opportunity product' object.

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. This is applicable only for self-serve subscription sync cases where Chargebee creates or updates the opportunities. Let's look at an example:

  • 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)
  • 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)
    • For a total opportunity amount of $125

Sync Rules for Quotes 

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.

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.

Configure Sync Rules for Plans and Addons 

Default Values for Products or Price Book Entries: Specify default values for mandatory fields in Salesforce. Available objects are Pricebook, and product.

Sync Rules for Custom Field in Plans: Allow custom fields to sync from Chargebee plans to Salesforce. Available objects are Pricebook, and Product.

Sync Rules for Custom Field in Addons: Allow custom fields to sync from Chargebee addons to Salesforce. Available objects are Pricebook, and Product.

Chargebee Settings 

Chargebee site settings: This section displays information of the connected Chargebee site.

Chargebee Sync Jobs and Logs: The number of logs generated by the integration could build up overtime. You can use the Chargebee sync Jobs and Logs section to set a frequency to automatically clean up the logs for the records that were successfully synced. Available options are Daily, Weekly, and Monthly.

Step 4: Validation 

Once you set the rules and click proceed, a pre-validation to sync the records will be established. In the case of errors, it will be displayed. It is recommended that you fix the issues and retry the validation. Learn more about how/what information is validated.

Step 5: Sync Records 

The first 10 records will be synced between Chargebee and Salesforce. Information such as Subscriptions, Plans, Add-ons, Customer, and Invoices will be synced. Using this feature you can ensure that the data sync happens as per the settings that you have configured. Click Run Initial Sync.

In case you face any issues, you can fix them and retry or choose to ignore them and proceed with the full sync. You can address these issues any time.

Once the initial sync is successful, click Proceed to run the full sync. This operation syncs all Subscriptions, Plans, Add-ons, Customer, Invoices, and Credit note data from Chargebee into Salesforce as per the configuration rules specified. That said, the first full sync will not create or update opportunities in Salesforce.

Next, enable Auto sync and set the frequency for the sync. You can choose to sync the data every hour, every 6 hours or once a day.

Managing Preferences 

Note

Once the settings are changed, historical records are unaffected unless mentioned otherwise.

You can manage the Sync Health by navigating to Chargebee Integration > Sync Health in your Salesforce App. This dashboard lists the last 5 sync jobs that are completed in reverse chronological order.

The Sync Logs tab lists the logs for individual records that are performed along with the status. By default, it displays only the failed sync records. But, you can change the setting by clicking the Filter icon and adding the filter.

The Sync Rules tab lists the Sync settings that you have initially configured. You can edit the sync rules from this page.

The Advanced Actions tab allows you to:

  • Add/remove domains
  • Retrieve historic data

Add/Remove Domain 

You can unlink an integration by clicking the Unlink Integration option. If you want to add a new Chargebee domain, click Get Started.

The Unlink Integration option is useful if you want to temporarily disconnect the integration for some reason. ‘Unlinking' does not clear any Chargebee data on Salesforce, but it will clear the stored Chargebee API key and remove scheduled sync jobs for the connected Chargebee site.

Retrieve Data 

You can also retrieve or resync any information such as an invoice or subscription that might have been accidentally deleted and needs to be fetched again from Chargebee, using the retrieve data tab.

Other Considerations 

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.

Example

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.

Considerations when using Account Hierarchy 

  • Account Hierarchy as a feature exists separately in both Salesforce  and Chargebee. You can sync an account hierarchy relationship that's set in Salesforce over to Chargebee.
  • When a Chargebee invoice or credit note is synced to Salesforce, it is linked to the account that corresponds to the invoice owner in the Account Hierarchy in Chargebee. For example, if say, Acme-Asia is invoiced for all charges incurred by Acme-India, then though a subscription shows up as related to Acme-India, the invoice for it (and any credit notes) would be related to Acme-Asia.
  • Also see notes under the following Chargebee actions in Salesforce:

Was this article helpful?
Loading…