Docs

Log in to read the version of docs relevant to your site, or use the dropdown versions

Salesforce Field-Mapping

This document describes the relationship between the various Chargebee and Salesforce fields. Field mapping is one of the most important steps as it creates a bidirectional linkage between the two systems and thereby gives greater control on the implications of the native salesforce settings.

Warning

Migration If you are migrating your Chargebee site from Product Catalog 1.0 to 2.0, the Salesforce integration package cannot be readily migrated. Contact support to perform the migration.

Object-Level Mapping

Chargebee objects are mapped to standard as well as custom objects in Salesforce. The latter are created by Chargebee. The table below shows the relationship between objects in either systems in terms of data flow.

Chargebee Object/Data

Salesforce Object (* indicates custom object)

CustomerAccount
Contact
Item (Plan/Addon/Charge)Product
Item PriceCB Item Price*
CB Pricing Tier*
Price Book Entry
QuoteCB Quote*
CB Quote Line Item*
CB Quote Product*
CB Quote Coupon*
SubscriptionOpportunity
Opportunity Product
CB Opportunity Product*
CB Opportunity Coupon*
CB Subscription*
Subscription Addon*
Coupon Line Items*
InvoiceCB Invoice*
CB Invoice Line Item*
CouponCB Coupon*
Credit NoteCB Credit Note*
CB Credit Note Allocation*
Chargebee site domain nameCB Site*

Field-Level Mapping for Standard Objects

Here we look at how fields in standard Salesforce objects are mapped to data in Chargebee. The notation used to represent Chargebee data is as seen in the [link_api]Chargebee backend API[].

Account

Accounts in Salesforce are mapped to customers in Chargebee. Given below is the default field-mapping.

Salesforce Field (* indicates custom field)Chargebee Field / Data
Account NameCustomer.company
PhoneCustomer.phone
Auto Collection*Customer.auto_collection
Billing StreetCustomer.billing_address.line1 + line2 + line3 (the field values are concatenated, separated by commas)
Billing CityCustomer.billing_address.city
Billing Zip/Postal CodeCustomer.billing_address.zip
Billing State/ProvinceCustomer.billing_address.state
Billing CountryCustomer.billing_address.country
Chargebee Billing Contact*Lookup to a contact that is used to populate billing contact details in sales driven automations.
Chargebee Email*Customer.email
Chargebee First Name*Customer.first_name
Chargebee Id*Customer.id
Chargebee Last Name*Customer.last_name
Chargebee Site*Lookup to CB Site object which in turn stores the domain name of the Chargebee site this account belongs to
Is Synced*Indicates whether the record has been mapped to Chargebee.
Locale*Customer.locale
Net Term Days*Customer.net_term_days
Payment Method Status*Customer.payment_method.status
Payment Method Type*Customer.payment_method.type
Sync with Chargebee*Checkbox that automates data sync from the account to Chargebee whenever a change is made to the account.
Taxability*Customer.taxability
VAT Number*Customer.vat_number
Business Entity*Lookup(CB Business Entity)

Contact

The Contact object is mapped to fields in the Customer object in Chargebee. The default mapping is given below.

Salesforce Field (* indicates custom field)Chargebee Field / Data
EmailCustomer.email
Name (composite field)Customer.first_name, Customer.last_name
PhoneCustomer.phone
Preferred currency*(Deprecated)
Payment Method Status*(Deprecated)
Payment Method Type*(Deprecated)
Net Term Days*(Deprecated)
Chargebee_Modified_Time*(Deprecated)
Auto collection*(Deprecated)
Sync with Chargebee*Checkbox that marks the contact – while it is attached to an account – as the one to consider for syncing with Chargebee.

Price Book

A single Price Book record is created for all the Chargebee sites that are connected to the Salesforce org.

Note:

Regardless of the number of connected sites and number of currency/frequency combinations configured in your Chargebee site for a particular plan, there can be only one Price Book created for all the connected Chargebee sites where only one billing frequency and currency combination for a particular plan is recorded. For example, an ‘Advanced' plan supports three currencies - USD, EUR, and AUD and 2 billing frequencies - annual and monthly). Out of the two billing frequencies, only one can be stored in a single standard or custom pricebook. The integration however relies primarily on the Item Price (custom object) for a specific price point associated with a product.

The fields used by the integration are as follows:

Salesforce Field (* indicates custom field)Chargebee Field / Data
CB Site*Lookup to CB Site object which in turn stores the domain name of the Chargebee site this price book belongs to.
Price Book NameCB Price Book prefixed with the Chargebee site domain name.

Price Book Entry

A price book entry record is created for each Chargebee plan and addon.

Product

Each plan and addon is synced into Salesforce as a Product record.

Salesforce Field (* indicates custom field)Chargebee Field / DataComments
Product CodePlan.id or Addon.id or Charge.id
List Priceitem_price.priceThe value is set to 0 when the Recurring charge model is volume, tiered, or stair-step.
Use Standard Price(Deprecated)Not in use for v1.38 and later versions
Currency (chargebeeapps__Currency__c)(Deprecated)(Deprecated)
Currency (CurrencyIsoCode)Plan.currency_code, Addon.currency_code, or Charge.currency_code
Setup Cost*(Deprecated)(Deprecated)
Trial Period Unit*(Deprecated)(Deprecated)
Trial Period Unit*(Deprecated)(Deprecated)
Bill Every*(Deprecated)(Deprecated)
Bill Every Unit*(Deprecated)(Deprecated)
Billing Cycles*(Deprecated)(Deprecated)
Free Quantity*(Deprecated)(Deprecated)
Recurring charge model*(Deprecated)(Deprecated)
Pricing Model*(Deprecated)(Deprecated)
Invoice Name*(Deprecated)(Deprecated)
Chargebee Modified Time*(Deprecated)(Deprecated)
Addon Applicability*(Deprecated)(Deprecated)
Resource Version*(Deprecated)(Deprecated)
Site*(Deprecated)(Deprecated)

Opportunity

Opportunity records are only created or modified by the integration when some form of opportunity handling has been configured. The following opportunity fields are updated by the integration:

Salesforce Field (* indicates custom field)Chargebee Field/Data
CB Subscription Id*(Deprecated)
Update Chargebee*A checkbox that determines whether a subscription should be created or updated in Chargebee when the opportunity is won.
Coupon*Deprecated field. The attached coupons can now be found in the CB Coupon related list for the opportunity.
CB Opportunity Type*Indicates the opportunity type in relation to Chargebee. This field is set by Chargebee and can have the following value: New subscription: indicates that the opportunity is for creating a new subscription.
Close Datesubscription.activated_at
Contract term Id*subscription.contract_term.id
Opportunity Currencysubscription.currency_code
AmountSum of Totals of the Opportunity Products.
Price bookThe Id of the price book for the Chargebee site.
Subscription Id*The id of the subscription in Chargebee that the opportunity is linked to.
StageThe stage of the opportunity may be set via the integration if configured accordingly.
Opportunity NameThis field is set to the company name of the customer record.
Business Entity*Lookup(CB Business Entity)

Opportunity Product

Opportunity Product records are only created or modified by the integration when some form of opportunity handling has been configured. The following opportunity product fields are updated by the integration:

Salesforce Field (* indicates custom field)Chargebee Field/Data
SubtotalSales Price x Quantity
CB Item Price*item_price.id
Total(Sales Price - Sales Price x Discount) x Quantity
QuantitySubscription.plan_quantity or Subscription.addons.quantity
Price Book EntryLookup(Price Book Entry)
List priceList Price from Price Book Entry
Sales PriceSubscription.plan_unit_price or Subscription.addons.unit_price
DiscountFor Chargebee plans, the discount percentage is calculated based on the plan's free quantity and the coupon discount.** For Chargebee addons and charges**, the discount percentage is calculated based on the coupon discount. By default, the integration considers all types of Chargebee coupons in the Discount calculation. However, for a given Chargebee site, if you want to exclude limited period or one-time coupons while calculating Discount, contact support@chargebee.com.
Service Period (days)*Subscription.event_based_addons.service_period_in_days
Billing Cycles*Subscription.remaining_billing_cycles or Subscription.addons.remaining_billing_cycles
Apply Charges*Subscription.event_based_addons.charge_once
Addon Event*Subscription.event_based_addons.on_event

Field-Level Mapping for Custom Objects

In this section, custom objects created by Chargebee in Salesforce are listed. The tables provide a field-level mapping between those objects and Chargebee entities. The Chargebee fields mentioned in the tables are attributes of resources available in Chargebee APIv2.

CB Item Price

CB Item Price in Salesforce is mapped to the Item Price resource in Chargebee.

Salesforce Field (* indicates custom field)Chargebee Field/Data
Trial Period Unittrial_period_unit
Trial Periodtrial_period
Statusstatus
Resource versionresource_version
Productname
Pricing Modelpricing_model
Price BookLookup to a Price Book record corresponding to the Chargebee site that the Item Price belongs to.
Priceprice
Period Unitperiod_unit
Periodperiod
Free Quantityfree_quantity
External Idid
Currencycurrency_code
CB Item Price Namename
Billing Cyclesbilling_cycles

CB Subscription

CB Subscription in Salesforce is mapped to the Subscription resource in Chargebee.

Salesforce Field (* indicates custom field)Chargebee Field/Data
AccountMaster-Detail(Account)
Action at term endsubscription.contract_term.action_at_term_end
Address Line 1subscription.shipping_address.line1
Address Line 2subscription.shipping_address.line2
Address Line 3subscription.shipping_address.line3
Business EntityLookup(CB Business Entity)
CB Customer Idsubscription.customer_id
CB Id"<domain name of the Chargebee site>"+"subscription.id"
CB Plan Idsubscription.subscription_items[].item_price_id of the plan.
CB SiteLookup(CB Site)
CB Subscription Idsubscription.id
CB Subscription Namesubscription.id
Chargebee Modified Timesubscription.updated_at
Citysubscription.shipping_address.city
Companysubscription.shipping_address.company
ContactLookup(Contact)
Countrysubscription.shipping_address.country
Created ByUser who triggers the sync or turns on auto sync.
Currencysubscription.currency_code
Current Term Endsubscription.current_term_end
Current Term Startsubscription.current_term_start
Due Invoices Countsubscription.due_invoices_count
Due Sincesubscription.due_since
Emailsubscription.shipping_address.email
First Namesubscription.shipping_address.first_name
Last Modified ByUser who triggers the sync or turns on auto sync.
Last Namesubscription.shipping_address.last_name
MRRsubscription.mrr
Next billing Amountinvoice_estimate.total
Next billing atsubscription.next_billing_at
OpportunityLookup(Opportunity)
Phonesubscription.shipping_address.phone
Plan Amountsubscription.subscription_items[].amount or subscription.subscription_items[].amount_in_decimal of the plan.
Plan Quantitysubscription.subscription_items[].quantity or subscription.subscription_items[].quantity_in_decimal of the plan.
Plan Unit Pricesubscription.subscription_items[].unit_price or subscription.subscription_items[].unit_price_in_decimal of the plan.
PO Numbersubscription.po_number
ProductLookup(Product)
Reason for cancellationsubscription.cancel_reason
Cancellation Reason Codesubscription.cancel_reason_code
Remaining Billing Cyclessubscription.remaining_billing_cycles
Resource Versionsubscription.resource_version
Site(Deprecated)
State/ County/ Provincesubscription.shipping_address.state
Subscription Activated Atsubscription.activated_at
Subscription Cancelled Atsubscription.cancelled_at
Subscription Created Atsubscription.created_at
Subscription Id"<domain name of the Chargebee site>"+"subscription.id"
Subscription Started Atsubscription.started_at
Subscription statussubscription.status
Total Duessubscription.total_dues
Trial Endsubscription.trial_end
Trial Startsubscription.trial_start
Zip/ Postal Codesubscription.shipping_address.zip

CB Invoice

The CB Invoice in Salesforce is mapped to the Invoices resource in Chargebee.

Salesforce FieldsChargebee Fields
AccountLookup(Account)
Amountinvoice.total
Business EntityLookup(CB Business Entity)
CB Customer CB Idinvoice.customer_id
CB Id"<domain name of the Chargebee site>"_invoice.id
CB Invoice Idinvoice.id
CB Invoice Nameinvoice.id
CB SiteLookup(CB Site)
CB SubscriptionLookup(CB Subscription)
CB Subscription CB Idinvoice.subscription_id
Chargebee Modified Timeinvoice.updated_at
Created ByLookup(User)
Due Amountinvoice.amount_due
Due Dateinvoice.due_date
Invoice Dateinvoice.date
Invoice IDinvoice.id
Last Modified ByLookup(User)
Next Retryinvoice.next_retry_at
Ownerinvoice.payment_owner
Paid Oninvoice.paid_at
PO Numberinvoice.po_number
Price Typeinvoice.price_type
Recurringinvoice.recurring
Resource Versioninvoice.resource_version
Statusinvoice.status
SubTotalinvoice.sub_total
Taxinvoice.tax
Vat Numberinvoice.vat_number

CB Invoice Line Item

The CB Invoice Line Item in Salesforce is mapped to the Invoices resource in Chargebee.

Salesforce FieldsChargebee Fields
Amountinvoice.line_items.amount
CB InvoiceMaster-Detail(CB Invoice)
CB Invoice CB Idinvoice.id
CB Invoice Line Item CB Idinvoice.line_items.id
CB Item PriceLookup(CB Item Price)
Created ByLookup(User)
Discount Amountinvoice.line_items.discount_amount
End Dateinvoice.line_items.date_to
Invoice Line Items Nameinvoice.line_items.name
Last Modified ByLookup(User)
Priceinvoice.line_items.unit_amount
ProductLookup(Product)
Quantityinvoice.line_items.quantity
Reason for tax exemptioninvoice.line_items.tax_exempt_reason
Start Dateinvoice.line_items.date_from
Tax Amountinvoice.line_items.tax_amount
Total amountinvoice.line_items.amount

CB Credit Note

The CB Credit Note in Salesforce is mapped to the Credit notes resource in Chargebee.

Salesforce FieldsChargebee Fields
AccountLookup(Account)
Allocated Amountcredit_notes.amount_allocated
Available Amountcredit_notes.amount_available
Business EntityLookup(CB Business Entity)
CB Credit Note Namecredit_notes.id
CB InvoiceMaster-Detail(CB Invoice)
CB Invoice Idcredit_notes.reference_invoice_id
CB SiteLookup(CB Site)
ContactLookup(Contact)
Created ByLookup(User)
CreditNote CB Idcredit_notes.id
Customer CB Idcredit_notes.customer_id
Issued Datecredit_notes.date
Last Modified ByLookup(User)
Price Typecredit_notes.price_type
Reasoncredit_notes.reason_code
Refunded Amountcredit_notes.amount_refunded
Refunded Atcredit_notes.refunded_at
Resource Versioncredit_notes.resource_version
Round-Off Amountcredit_notes.round_off_amount
Statuscredit_notes.status
Sub Totalcredit_notes.sub_total
Totalcredit_notes.total
Typecredit_notes.type
Voided Atcredit_notes.voided_at

CB Coupon

The CB coupon in Salesforce is mapped to the Coupons resource in Chargebee.

Salesforce FieldsChargebee Fields
Addon Idcoupon.item_type.addon
Apply Oncoupon.apply_on
CB Coupon Idcoupon.id
CB Id"<domain name of the Chargebee site>"_coupon.id
CB SiteLookup(CB Site)
Charge Constraintcoupon.item_constraints.item_type
Charge Idcoupon.item_type.charge
Chargebee Modified Timecoupon.updated_at
Coupon Created Atcoupon.created_at
Coupon Idcoupon.id
Coupon Namecoupon.name
Created ByLookup(User)
Discount Amountcoupon.discount_amount
Discount Percentagecoupon.discount_percentage
Discount Typecoupon.discount_type
Duration Monthcoupon.duration_month
Duration Typecoupon.duration_type
Invoice Namecoupon.invoice_name
Last Modified ByLookup(User)
Max Redemptionscoupon.max_redemptions
OwnerLookup(User,Group)
Plan Constraintcoupon.item_constraints.item_type
Plan Idcoupon.plan_id
Redemptionscoupon.redemptions
Resource Versioncoupon.resource_version
Statuscoupon.status
Valid Tillcoupon.valid_till

Was this article helpful?