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.
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) |
|---|---|
| Customer | Account |
| Contact | |
| Item (Plan/Addon/Charge) | Product |
| Item Price | CB Item Price* |
| CB Pricing Tier* | |
| Price Book Entry | |
| Quote | CB Quote* |
| CB Quote Line Item* | |
| CB Quote Product* | |
| CB Quote Coupon* | |
| Subscription | Opportunity |
| Opportunity Product | |
| CB Opportunity Product* | |
| CB Opportunity Coupon* | |
| CB Subscription* | |
| Subscription Addon* | |
| Coupon Line Items* | |
| Invoice | CB Invoice* |
| CB Invoice Line Item* | |
| Coupon | CB Coupon* |
| Credit Note | CB Credit Note* |
| CB Credit Note Allocation* | |
| Chargebee site domain name | CB 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 Name | Customer.company |
| Phone | Customer.phone |
| Auto Collection* | Customer.auto_collection |
| Billing Street | Customer.billing_address.line1 + line2 + line3 (the field values are concatenated, separated by commas) |
| Billing City | Customer.billing_address.city |
| Billing Zip/Postal Code | Customer.billing_address.zip |
| Billing State/Province | Customer.billing_address.state |
| Billing Country | Customer.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 |
|---|---|
Customer.email | |
| Name (composite field) | Customer.first_name, Customer.last_name |
| Phone | Customer.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 Name | CB 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 / Data | Comments |
|---|---|---|
| Product Code | Plan.id or Addon.id or Charge.id | |
| List Price | item_price.price | The 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 Date | subscription.activated_at |
| Contract term Id* | subscription.contract_term.id |
| Opportunity Currency | subscription.currency_code |
| Amount | Sum of Totals of the Opportunity Products. |
| Price book | The Id of the price book for the Chargebee site. |
| Subscription Id* | The id of the subscription in Chargebee that the opportunity is linked to. |
| Stage | The stage of the opportunity may be set via the integration if configured accordingly. |
| Opportunity Name | This 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 |
|---|---|
| Subtotal | Sales Price x Quantity |
| CB Item Price* | item_price.id |
| Total | (Sales Price - Sales Price x Discount) x Quantity |
| Quantity | Subscription.plan_quantity
or
Subscription.addons.quantity |
| Price Book Entry | Lookup(Price Book Entry) |
| List price | List Price from Price Book Entry |
| Sales Price | Subscription.plan_unit_price
or
Subscription.addons.unit_price |
| Discount | For 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 Chargebee Support. |
| 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 Unit | trial_period_unit |
| Trial Period | trial_period |
| Status | status |
| Resource version | resource_version |
| Product | name |
| Pricing Model | pricing_model |
| Price Book | Lookup to a Price Book record corresponding to the Chargebee site that the Item Price belongs to. |
| Price | price |
| Period Unit | period_unit |
| Period | period |
| Free Quantity | free_quantity |
| External Id | id |
| Currency | currency_code |
| CB Item Price Name | name |
| Billing Cycles | billing_cycles |
CB Subscription
CB Subscription in Salesforce is mapped to the Subscription resource in Chargebee.
| Salesforce Field (* indicates custom field) | Chargebee Field/Data |
|---|---|
| Account | Master-Detail(Account) |
| Action at term end | subscription.contract_term.action_at_term_end |
| Address Line 1 | subscription.shipping_address.line1 |
| Address Line 2 | subscription.shipping_address.line2 |
| Address Line 3 | subscription.shipping_address.line3 |
| Business Entity | Lookup(CB Business Entity) |
| CB Customer Id | subscription.customer_id |
| CB Id | "<domain name of the Chargebee site>"+"subscription.id" |
| CB Plan Id | subscription.subscription_items[].item_price_id of the plan. |
| CB Site | Lookup(CB Site) |
| CB Subscription Id | subscription.id |
| CB Subscription Name | subscription.id |
| Chargebee Modified Time | subscription.updated_at |
| City | subscription.shipping_address.city |
| Company | subscription.shipping_address.company |
| Contact | Lookup(Contact) |
| Country | subscription.shipping_address.country |
| Created By | User who triggers the sync or turns on auto sync. |
| Currency | subscription.currency_code |
| Current Term End | subscription.current_term_end |
| Current Term Start | subscription.current_term_start |
| Due Invoices Count | subscription.due_invoices_count |
| Due Since | subscription.due_since |
subscription.shipping_address.email | |
| First Name | subscription.shipping_address.first_name |
| Last Modified By | User who triggers the sync or turns on auto sync. |
| Last Name | subscription.shipping_address.last_name |
| MRR | subscription.mrr |
| Next billing Amount | invoice_estimate.total |
| Next billing at | subscription.next_billing_at |
| Opportunity | Lookup(Opportunity) |
| Phone | subscription.shipping_address.phone |
| Plan Amount | subscription.subscription_items[].amount or subscription.subscription_items[].amount_in_decimal of the plan. |
| Plan Quantity | subscription.subscription_items[].quantity or subscription.subscription_items[].quantity_in_decimal of the plan. |
| Plan Unit Price | subscription.subscription_items[].unit_price or subscription.subscription_items[].unit_price_in_decimal of the plan. |
| PO Number | subscription.po_number |
| Product | Lookup(Product) |
| Reason for cancellation | subscription.cancel_reason |
| Cancellation Reason Code | subscription.cancel_reason_code |
| Remaining Billing Cycles | subscription.remaining_billing_cycles |
| Resource Version | subscription.resource_version |
| Site | (Deprecated) |
| State/ County/ Province | subscription.shipping_address.state |
| Subscription Activated At | subscription.activated_at |
| Subscription Cancelled At | subscription.cancelled_at |
| Subscription Created At | subscription.created_at |
| Subscription Id | "<domain name of the Chargebee site>"+"subscription.id" |
| Subscription Started At | subscription.started_at |
| Subscription status | subscription.status |
| Total Dues | subscription.total_dues |
| Trial End | subscription.trial_end |
| Trial Start | subscription.trial_start |
| Zip/ Postal Code | subscription.shipping_address.zip |
| Primary Card Expiry | customer.payment_source.expiry_month customer.payment_source.expiry_year |
| Primary Last 4 | customer.payment_source.last4 |
CB Invoice
The CB Invoice in Salesforce is mapped to the Invoices resource in Chargebee.
| Salesforce Fields | Chargebee Fields |
|---|---|
| Account | Lookup(Account) |
| Amount | invoice.total |
| Business Entity | Lookup(CB Business Entity) |
| CB Customer CB Id | invoice.customer_id |
| CB Id | "<domain name of the Chargebee site>"_invoice.id |
| CB Invoice Id | invoice.id |
| CB Invoice Name | invoice.id |
| CB Site | Lookup(CB Site) |
| CB Subscription | Lookup(CB Subscription) |
| CB Subscription CB Id | invoice.subscription_id |
| Chargebee Modified Time | invoice.updated_at |
| Created By | Lookup(User) |
| Due Amount | invoice.amount_due |
| Due Date | invoice.due_date |
| Invoice Date | invoice.date |
| Invoice ID | invoice.id |
| Last Modified By | Lookup(User) |
| Next Retry | invoice.next_retry_at |
| Owner | invoice.payment_owner |
| Paid On | invoice.paid_at |
| PO Number | invoice.po_number |
| Price Type | invoice.price_type |
| Recurring | invoice.recurring |
| Resource Version | invoice.resource_version |
| Status | invoice.status |
| SubTotal | invoice.sub_total |
| Tax | invoice.tax |
| Vat Number | invoice.vat_number |
CB Invoice Line Item
The CB Invoice Line Item in Salesforce is mapped to the Invoices resource in Chargebee.
| Salesforce Fields | Chargebee Fields |
|---|---|
| Amount | invoice.line_items.amount |
| CB Invoice | Master-Detail(CB Invoice) |
| CB Invoice CB Id | invoice.id |
| CB Invoice Line Item CB Id | invoice.line_items.id |
| CB Item Price | Lookup(CB Item Price) |
| Created By | Lookup(User) |
| Discount Amount | invoice.line_items.discount_amount |
| End Date | invoice.line_items.date_to |
| Invoice Line Items Name | invoice.line_items.name |
| Last Modified By | Lookup(User) |
| Price | invoice.line_items.unit_amount |
| Product | Lookup(Product) |
| Quantity | invoice.line_items.quantity |
| Reason for tax exemption | invoice.line_items.tax_exempt_reason |
| Start Date | invoice.line_items.date_from |
| Tax Amount | invoice.line_items.tax_amount |
| Total amount | invoice.line_items.amount |
CB Credit Note
The CB Credit Note in Salesforce is mapped to the Credit notes resource in Chargebee.
| Salesforce Fields | Chargebee Fields |
|---|---|
| Account | Lookup(Account) |
| Allocated Amount | credit_notes.amount_allocated |
| Available Amount | credit_notes.amount_available |
| Business Entity | Lookup(CB Business Entity) |
| CB Credit Note Name | credit_notes.id |
| CB Invoice | Master-Detail(CB Invoice) |
| CB Invoice Id | credit_notes.reference_invoice_id |
| CB Site | Lookup(CB Site) |
| Contact | Lookup(Contact) |
| Created By | Lookup(User) |
| CreditNote CB Id | credit_notes.id |
| Customer CB Id | credit_notes.customer_id |
| Issued Date | credit_notes.date |
| Last Modified By | Lookup(User) |
| Price Type | credit_notes.price_type |
| Reason | credit_notes.reason_code |
| Refunded Amount | credit_notes.amount_refunded |
| Refunded At | credit_notes.refunded_at |
| Resource Version | credit_notes.resource_version |
| Round-Off Amount | credit_notes.round_off_amount |
| Status | credit_notes.status |
| Sub Total | credit_notes.sub_total |
| Total | credit_notes.total |
| Type | credit_notes.type |
| Voided At | credit_notes.voided_at |
CB Coupon
The CB coupon in Salesforce is mapped to the Coupons resource in Chargebee.
| Salesforce Fields | Chargebee Fields |
|---|---|
| Addon Id | coupon.item_type.addon |
| Apply On | coupon.apply_on |
| CB Coupon Id | coupon.id |
| CB Id | "<domain name of the Chargebee site>"_coupon.id |
| CB Site | Lookup(CB Site) |
| Charge Constraint | coupon.item_constraints.item_type |
| Charge Id | coupon.item_type.charge |
| Chargebee Modified Time | coupon.updated_at |
| Coupon Created At | coupon.created_at |
| Coupon Id | coupon.id |
| Coupon Name | coupon.name |
| Created By | Lookup(User) |
| Discount Amount | coupon.discount_amount |
| Discount Percentage | coupon.discount_percentage |
| Discount Type | coupon.discount_type |
| Duration Month | coupon.duration_month |
| Duration Type | coupon.duration_type |
| Invoice Name | coupon.invoice_name |
| Last Modified By | Lookup(User) |
| Max Redemptions | coupon.max_redemptions |
| Owner | Lookup(User,Group) |
| Plan Constraint | coupon.item_constraints.item_type |
| Plan Id | coupon.plan_id |
| Redemptions | coupon.redemptions |
| Resource Version | coupon.resource_version |
| Status | coupon.status |
| Valid Till | coupon.valid_till |
Articles & FAQs
Was this article helpful?