Salesforce Chargebee Integration: The Complete Guide to Setup, Sync Rules and Quote-to-Cash
Sales closes the deal in Salesforce. Chargebee bills it, collects it and renews it. The integration decides whether the two agree about the customer, the subscription and the revenue. This guide covers the options, the prerequisites, every setup step, the sync rules that matter, pricing and price books, and how to fix sync errors, based on Chargebee's current documentation.
Key Takeaways
- The Salesforce Chargebee integration is Chargebee's own managed package. It maps each Chargebee customer to one Salesforce account, syncs plans, subscriptions, quotes, invoices and credit notes into Salesforce, and lets reps create and change subscriptions from Salesforce.
- It needs Salesforce Enterprise Edition or above, and Chargebee charges for it on top of the regular plan fee.
- Chargebee data reaches Salesforce on a schedule (every 10 minutes at the fastest), not in real time. Editing a synced field on a Salesforce page does not change Chargebee; changes go through Chargebee actions.
- The sync rules decide most of the outcome: how customers match accounts, what happens to opportunities, and whether a won opportunity creates the subscription automatically.
- Chargebee prices live in the CB Item Price object, not in price book entries. Reps should add products with Manage CB Products, never the standard Add Products button.
What is the Salesforce Chargebee integration? It is the connection between Salesforce, where sales manages accounts and opportunities, and Chargebee, the subscription billing platform that holds the product catalog, subscriptions, invoices and payments. Chargebee's managed package syncs billing data into Salesforce and adds Chargebee actions to Salesforce records, so a closed-won opportunity can become a live subscription without finance re-keying the deal.
We first published this guide in June 2026. This version is rebuilt and checked against Chargebee's documentation, its AppExchange listing and webhook reference in November 2026. It corrects several common assumptions, including real-time sync and two-way field editing, and adds the prerequisites, sync rules, pricing behaviour and error codes. It is written for RevOps, finance systems and Salesforce teams at growing and mid-market companies that sell subscriptions, and for the leaders who need the CRM and billing numbers to match.
What Does the Salesforce Chargebee Integration Actually Do?
It gives sales a working copy of billing inside Salesforce, and gives billing a clean handoff from sales. Chargebee customers, plans, subscriptions, quotes, invoices and credit notes sync into Salesforce. Reps create quotes and subscriptions from accounts and opportunities, and Chargebee runs invoicing, payments and renewals. Chargebee calls it a one-to-one link: one customer, one account.
Record sync
Customers to accounts and contacts, items to products, item prices to price book entries, and subscriptions, quotes, invoices, coupons and credit notes to Chargebee custom objects.
Actions in Salesforce
Create, change, pause, resume and cancel subscriptions, send quotes, generate checkout links, add charges and issue refunds, without logging in to Chargebee.
Opportunity automation
Rules that create or update opportunities from Chargebee subscriptions, create the subscription when an opportunity is won, and raise renewal opportunities for fixed-term subscriptions.
Chargebee's product page for the Salesforce integration describes three workflows it supports: sales-driven, where reps create subscriptions from Salesforce; self-serve, where customers buy on a checkout page and Salesforce records the win; and hybrid, which mixes both.
Why Integrate Chargebee with Salesforce?
Because the handoff from a signed deal to a correct first invoice is where subscription revenue leaks. Without the integration, someone re-enters every deal in Chargebee, renewals are tracked outside the CRM, and Salesforce reports bookings that billing never collected. Connecting them removes the re-keying and gives each team the other team's facts.
With the integration in place, the CB Subscription record in Salesforce carries the subscription status, MRR, current term dates, next billing date and amount, and the count of unpaid invoices, according to Chargebee's field mapping reference. That is enough for account teams to have an informed renewal or collections conversation inside Salesforce.
Which Salesforce Chargebee Integration Approach Is Right for You?
Start with Chargebee's native Salesforce app unless you already run Salesforce CPQ or have a requirement the app cannot meet. The native app covers the standard quote-to-cash flow and is maintained by Chargebee. Salesforce CPQ users have a separate Chargebee package. Custom API work and iPaaS tools fill gaps around the app; they rarely replace it.
| Approach | What it is | Best for | Watch out for |
|---|---|---|---|
| Chargebee for Salesforce (native app) | Chargebee's managed package: sync, custom objects, actions on accounts, opportunities, subscriptions, quotes and invoices | Most teams running the standard Salesforce opportunity and product model | Extra Chargebee fee; Enterprise Edition or above; scheduled, not real-time, sync |
| Chargebee for Salesforce CPQ | A separate Chargebee package that syncs customers and subscriptions with Salesforce CPQ quotes and opportunities | Orgs already quoting in Salesforce CPQ | Early access; needs Salesforce CPQ 242.2 or higher; cannot run alongside the native app |
| Chargebee API and webhooks | Custom Apex or middleware calling Chargebee's REST API and consuming its webhook events | Requirements the app does not cover: custom objects, usage feeds, provisioning, other systems in the loop | You own retries, duplicates, ordering and monitoring (Section 11) |
| iPaaS (MuleSoft, Workato, Celigo and similar) | A platform with Chargebee and Salesforce connectors and visual flows | Multi-system flows, such as Salesforce, Chargebee and an ERP together | Another subscription to run; field mapping still has to be designed |
The CPQ details come from Chargebee's CPQ integration setup guide. Both Chargebee packages appear under the Chargebee AppExchange listing, which in November 2026 showed a starting price of US$1,500 per company per month; confirm current pricing with Chargebee, since its documentation says the integration is charged separately from your Chargebee plan.
A common pattern is a hybrid: the native app for customers, subscriptions and quotes, plus a small number of webhook-driven automations for events the app does not surface the way you want. Our Chargebee API and integration development team builds that second layer.
What Do You Need Before You Connect Chargebee to Salesforce?
Salesforce Enterprise Edition or above, the integration enabled on your Chargebee plan, a registered My Domain, a dedicated Chargebee API key, and the right permission sets. Check the edition and the commercial side first, because they decide whether the native app is an option at all. Then prepare a Salesforce sandbox and a Chargebee test site to connect first.
| Requirement | Detail |
|---|---|
| Salesforce edition | Enterprise Edition and above. Classic and Lightning are both supported. |
| Chargebee plan | The Salesforce integration is not included in regular plan fees and costs extra on every plan. |
| My Domain | Registered and deployed in Salesforce (required from package version 1.38). |
| Integration tab | Chargebee Integration tab set to Default On for the System Administrator profile. |
| Permission sets | ChargebeeForSalesforceAdminUser for admins and ChargebeeForStandardUsers for other users, plus your own permission set for the master-detail objects: CB Subscription, CB Opportunity Coupon, CB Opportunity Product, Coupon Line Item and Subscription Addon. |
| Remote site | Your Chargebee site URL allow-listed under Remote Site Settings. |
| API key | A full-access Chargebee API key, created only for Salesforce, so it can be rotated without breaking anything else. |
Sources: Chargebee's Salesforce integration overview and integration guide, and Salesforce's My Domain overview. One more detail to plan for: the Chargebee package does not update itself. You check the installed version under Setup › Installed Packages and ask Chargebee support to upgrade it, then run any post-update scripts the integration lists under Advanced Actions.
Clean data first, too. The integration matches customers to accounts on one field, so duplicate accounts, duplicate Chargebee customers and blank email or ID fields become sync errors on day one. Our guide to Salesforce profiles and permission sets explains how to grant the Chargebee access with permission sets rather than cloned profiles.
How Do You Set Up the Salesforce Chargebee Integration, Step by Step?
Install the package from Chargebee, connect the site inside Salesforce, set the sync rules, validate, sync ten records, then run the full sync and switch on auto sync. Do the whole sequence in a sandbox connected to a Chargebee test site first. Configuration changes apply only to records synced afterwards, so getting the rules right before the full sync saves rework.
Auto sync can run every 10 minutes, every hour, every 6 hours or daily, and records are created and updated under the name of the user who switched it on, so use a dedicated integration user rather than a person's login. Set up failure emails too, but choose the interval carefully: Chargebee's guide notes that a 10-minute sync with an alert on every job can send 144 emails a day, all counted against your org's email limits.
How Do Chargebee Objects Map to Salesforce?
Customers map to accounts and contacts, items to products, and subscriptions to opportunities plus a CB Subscription custom object. Quotes, invoices, coupons and credit notes arrive as Chargebee custom objects. Billing data does not land on Salesforce orders or contracts; it lands on the CB objects, which are linked to the account and, for subscriptions, to the opportunity.
| Chargebee | Salesforce | Notes |
|---|---|---|
| Customer | Account, Contact | One customer to one account; person accounts supported |
| Item (plan, addon, charge) | Product | One product per plan and addon |
| Item price | Price Book Entry, CB Item Price, CB Pricing Tier | CB Item Price is the reference for current prices (Section 09) |
| Subscription | Opportunity, Opportunity Product, CB Subscription, Subscription Addon, CB Opportunity Product, CB Opportunity Coupon, Coupon Line Items | CB Subscription holds status, MRR, term dates and next billing |
| Quote | CB Quote and its line item, product and coupon objects | Created and sent from Salesforce |
| Invoice | CB Invoice, CB Invoice Line Item | Linked to the account that owns the invoice in an account hierarchy |
| Coupon | CB Coupon | |
| Credit note | CB Credit Note, CB Credit Note Allocation |
Source: Chargebee's object and field mapping. The diagram below shows the same model at a glance.
Which direction does data flow?
Billing data flows from Chargebee into Salesforce on each sync. Data reaches Chargebee from Salesforce through Chargebee actions: creating or changing a subscription, sending a quote, or the Create/Update Chargebee Customer action on an account. Chargebee's actions guide is explicit that editing fields on Salesforce pages is not synced to Chargebee, with the account as the only exception. An account also carries a Sync with Chargebee checkbox that pushes account changes automatically.
Custom fields can be added in either direction, but each pair syncs one way only. Watch picklists: if a Salesforce country picklist holds "United States" and Chargebee sends "USA", the record fails to sync. Chargebee recommends text fields on the Salesforce side, or dropdown custom fields in Chargebee whose values match.
Which Chargebee Sync Rules Matter Most in Salesforce?
Three groups of rules decide almost everything: how Chargebee customers find their Salesforce accounts, how subscriptions affect opportunities, and whether a won opportunity creates the subscription. Choose them from your sales motion. A self-serve business pulls data from Chargebee into Salesforce; a sales-led business pushes deals from Salesforce into Chargebee; many do both.
Accounts: matching and creation
- Which customers sync. All customers, or only customers with at least one subscription, optionally excluding some by subscription status, price point or custom field.
- The matching pair. One Chargebee field (customer ID, email, phone, company or a custom field) matched to one Salesforce account field. Chargebee warns against company names, because "Acme Inc" and "Acme Inc." will not match.
- When a match is found. Overwrite the account with Chargebee data, fill only empty fields, or map only, which links the records without changing any Salesforce data.
- When no match is found. Find and convert a matching lead by email (optionally creating an opportunity), always create an account, or do nothing.
Opportunities: what happens when Chargebee changes
| Event in Chargebee | Options | Typical choice |
|---|---|---|
| New subscription syncs for the first time | Create New, Map Existing (link the latest open opportunity on the account), Do Nothing | Map Existing for sales-led; Create New for self-serve |
| Trial subscription | Create an opportunity at a separate trial stage, or not | On, if sales works trials |
| Upgrade | Create New, Update Existing, Do Nothing | Create New, to track expansion as its own opportunity |
| Cancellation | Update Existing to a chosen stage, or Do Nothing | Update Existing, so churn is visible in pipeline reports |
Opportunities created in Salesforce
For sales-led deals, three switches matter. Chargebee can move the opportunity to a chosen stage once a customer pays through a checkout link. It can replace the opportunity's products with the subscription's products. And it can create, upgrade or renew the subscription automatically when the opportunity is won. That last switch is the quote-to-cash automation most teams want; turn it on only after products, price books and required fields are reliable, because every won opportunity will then bill a customer.
Renewal opportunities
For subscriptions with a fixed number of billing cycles, Chargebee can create renewal opportunities on a schedule and keep them updated as the subscription changes. A renewed term closes the opportunity as won and a cancellation closes it as lost. It skips subscriptions whose contract term auto-renews. If reps edit renewal products by hand, set the Renewal Opportunity Behavior field to lock the line items, or the next sync will overwrite them. All of these options are documented in Chargebee's integration guide.
What Can Sales and Finance Do in Salesforce After the Integration?
Most day-to-day subscription work. Chargebee adds buttons to accounts, opportunities, CB Subscription, CB Quote and CB Invoice records. Reps quote and create subscriptions; account managers change, pause or cancel them; finance can refund an invoice. Chargebee still does the billing logic, proration and payment collection behind each action.
| Record | Chargebee actions available |
|---|---|
| Account | Create/Update Chargebee Customer, set account hierarchy, add a charge, update payment method, invoice unbilled charges, create a subscription, generate a checkout URL |
| Opportunity | Manage CB Products, create or change a subscription, quotes for new business, amendments, renewals and one-time charges, subscriptions with ramps |
| CB Subscription | Change, cancel, pause, resume, change next billing date, add a charge, sync the due invoice count, modify the start date or a scheduled cancellation |
| CB Quote | Send email, convert to a subscription, extend expiry, generate a PDF, sync to the opportunity |
| CB Invoice | Issue refunds, download the invoice PDF |
Three features help governance. Access Control under Advanced Actions sets read-only or write access per field (unit prices, billing duration, auto collection and others) for Salesforce public groups, so you can stop reps editing prices. Quotes can be held until a Salesforce approval process approves them before they are emailed. And subscription creation and changes are available as actions in Salesforce Flow Builder, as Chargebee describes in its Flow Builder article, so they can sit inside a guided screen flow.
How Do Chargebee Prices Sync to Salesforce Products and Price Books?
Products sync, but prices need care. Chargebee stores a price per billing frequency per currency, while Salesforce allows one price book entry per currency. So Chargebee sets the price book entry once and does not update it when prices change. The current prices live in the CB Item Price object, which Chargebee treats as the source of truth.
- Add products with Manage CB Products. It fetches current Chargebee prices for every frequency. The standard Add Products button does not.
- Report from CB Item Price, or update price book entries yourself, by hand or with automation, if a report needs them.
- Standard or advanced price books. By default, Chargebee populates one CB price book. Advanced multi-price-book mode lets you place plans, addons and charges in your own price books, but your team adds them there manually.
- One-time charges are not opportunity products when Chargebee updates an opportunity from a subscription. A US$100 monthly plan with a US$250 setup fee gives an opportunity worth the recurring items only.
These rules come from Chargebee's article on how Chargebee pricing syncs to Salesforce. Agree a change process with finance: when a price or plan changes in Chargebee, decide in the same change who updates the Salesforce side, so quotes never use an old price.
Which Quote-to-Cash Workflows Should You Automate First?
Automate the handoff from won opportunity to subscription first, then renewals, then the signals that warn of churn. Each of the five workflows below uses native integration settings or a simple Salesforce flow on synced data, so none needs custom code to start.
Closed won to subscription
Turn on automatic subscription creation when an opportunity is won. Products, quantities and coupons come from the opportunity's Manage CB Products lines, and Chargebee raises the first invoice under its normal billing rules.
Renewal opportunities
Enable renewal opportunities for fixed-term subscriptions and assign them through your normal opportunity assignment. Renewed terms close as won and cancellations as lost.
Upgrades as expansion
Set upgrades to Create New, so each expansion is its own opportunity and net revenue retention can be reported from Salesforce.
Unpaid invoice follow-up
Trigger a task for the account owner when Due Invoices Count on a key account's CB Subscription goes above zero. Chargebee's dunning keeps retrying the payment; the task adds a person for accounts that matter.
Cancellation and downgrade alerts
Update the existing opportunity on cancellation, and alert the account team when a CB Subscription's status changes to cancelled or non-renewing, or its MRR drops.
One caveat for workflow 4: Chargebee's field reference notes that Due Invoices Count only refreshes on a sync when the subscription itself has changed, which is why a Sync Due Invoice Count action exists. Build the flow on fields that update reliably, or schedule that action for key accounts. The AppExchange listing also describes alerts on MRR changes, cancellations, downgrades, payment failures and pauses by email and in Salesforce, so check what your edition includes before building your own.
When Do You Need the Chargebee API and Webhooks Instead?
When an event must reach Salesforce or another system faster than the scheduled sync, or must change data the package does not manage. Examples are provisioning a product account the moment a subscription activates, feeding usage into metered plans, or writing billing events to custom objects. Chargebee's webhooks push each event to your endpoint, but they must be consumed carefully.
What Chargebee guarantees. A delivery succeeds only on a 2XX response. A failed call is retried up to seven times: 2 minutes, 6 minutes, 30 minutes, 1 hour, 5 hours, 1 day and 2 days after the previous attempt. Failed webhooks can also be resent manually.
What your consumer must handle. Retries mean the same event can arrive more than once, so deduplicate on the event ID. Payloads are point-in-time snapshots that can arrive out of order, so an older state must never overwrite a newer one. Log and alert on failures instead of swallowing them.
The retry schedule and duplicate guidance come from Chargebee's webhook settings and events API documentation. In Salesforce, a common design receives the webhook in middleware or a secured endpoint, publishes a Platform Event, and lets Apex or a flow update records, so retries and errors are visible in one place. Keep the native package for what it does well and add custom code only for the gap.
Why Is Chargebee Not Syncing with Salesforce, and How Do You Fix It?
Open Chargebee Settings in Salesforce, check Sync Health, then read the Reason and Solution fields in Sync Logs. Most failures are a dependency that has not synced yet, or a customer that matches the wrong number of accounts. Failed records retry twice a day; after the tenth failed attempt the error turns from Soft to Hard and must be retried by hand.
| Error reason | What it means | Fix |
|---|---|---|
| ASSOCIATED_CUSTOMER_NOT_SYNCED | The subscription, quote, invoice or credit note's customer is not in Salesforce yet | Fix the customer's sync error first; the dependent record follows |
| ASSOCIATED_ITEMPRICE_NOT_SYNCED / ASSOCIATED_COUPONS_NOT_SYNCED | A price or coupon on the subscription or quote has not synced | Sync or fix the item price or coupon named in the Solution field |
| MULTIPLE_ENTITIES_MATCHING | One customer matches several accounts or contacts | Merge duplicates, or choose a unique matching field |
| DUPLICATE_CUSTOMER | The matching account is already linked to another customer | Merge the duplicate Chargebee customers, or correct the match value |
| MATCHING_FIELD_EMPTY | The customer has no value in the matching field | Populate it, or leave it empty on purpose to skip the record |
| MULTIPLE_LEADS_MATCHING | Lead conversion found more than one lead with the email | Merge the leads |
| PRICEBOOK_DOES_NOT_EXIST / ITEM_DOES_NOT_EXIST | A price book or product failed to create, often because of a validation rule | Relax or adjust the rule, set default values for required fields, and resync |
Two places hold the logs. The Sync Logs tab covers data going from Salesforce to Chargebee, and the CB Sync Log object covers data coming from Chargebee into Salesforce; always trace a record by its Chargebee ID. If synced records were deleted by mistake, Advanced Actions › Retrieve Data brings them back by date range or ID. Other frequent causes are picklist mismatches, Salesforce validation rules or required fields with no default value set in the integration, and a lead process or workflow that blocks lead conversion.
What Does a Good Salesforce Chargebee Implementation Look Like?
It starts with the deal desk and the catalog, not the package. Decide which system owns each record and field, how your real deals (ramps, discounts, one-time fees) map to Chargebee items, and what finance needs to close the month. The sync rules then follow from those decisions, and testing proves them on real deals.
| Phase | Decisions and work | Done when |
|---|---|---|
| 1. Design | System of record per field; account matching key; opportunity and renewal rules; catalog and price book model; approval rules | A signed-off mapping and rules document |
| 2. Prepare | Edition and licence check; My Domain; permission sets; duplicate cleanup; validation rules and required-field defaults | Sandbox validation passes |
| 3. Configure and test | Sync rules, field mapping, access control, flows, in a sandbox against a Chargebee test site | New, upgrade, renewal and cancellation test deals match on both sides |
| 4. Go live | Production connection, initial and full sync, auto sync, failure alerts, training | Sync logs stay clean for a full billing cycle |
| 5. Run | Weekly log review; package upgrades; catalog change process; reporting | Finance and sales report the same MRR |
This is how we approached it for a US AI-driven SaaS company in a published Salesforce, Chargebee and PandaDoc quote-to-cash case study. Salesforce stayed the system of record for accounts and opportunities, Chargebee ran billing and subscriptions, and PandaDoc handled agreements and eSignature. Reps quote in Salesforce with Chargebee's CPQ capability, a Salesforce flow generates the agreement, and after signature Chargebee creates the invoice and subscription and returns the subscription ID to Salesforce, with no middleware. The case study reports 13 automated steps from opportunity to subscription, delivered in five phases over about 10 weeks.
For the wider picture, see our Chargebee implementation service, which covers catalog design, migration and cutover, and Salesforce for SaaS companies.
The Bottom Line
The Salesforce Chargebee integration works when Salesforce owns the deal, Chargebee owns the bill, and the sync rules say so explicitly. Twopir Consulting designs and delivers Chargebee consulting and integrations with Salesforce, from catalog and sync rules to quote-to-cash automation, custom webhooks and support after go-live.
- 1
Confirm Enterprise Edition and the Chargebee integration add-on before you plan anything else.
- 2
Pick a unique matching field and clean duplicate accounts and customers first.
- 3
Choose opportunity, upgrade, cancellation and renewal rules from your sales motion.
- 4
Quote with Manage CB Products and treat CB Item Price as the price reference.
- 5
Test in a sandbox against a Chargebee test site, then review the sync logs every week.
Make Salesforce and Chargebee Report the Same Revenue
Tell us how you sell and bill today, and where the handoff breaks. We will map the sync rules, the catalog and the quote-to-cash flow your teams need.
Schedule a Discovery CallFrequently Asked Questions
Yes. Chargebee provides its own managed package for Salesforce. It maps each Chargebee customer to one Salesforce account, syncs plans, subscriptions, quotes, invoices, coupons and credit notes into Salesforce, and adds actions that let users create and manage subscriptions and quotes from Salesforce records. A separate package exists for Salesforce CPQ.
Chargebee supports Salesforce Enterprise Edition and above, in both Classic and Lightning. The integration also costs extra on top of your Chargebee plan, whatever plan you are on, so confirm both the edition and the commercial terms before planning the project.
No. Data from Chargebee reaches Salesforce on a schedule you choose: every 10 minutes, every hour, every 6 hours or daily. Actions taken from Salesforce, such as creating or changing a subscription, are sent to Chargebee straight away. For events that must arrive faster, teams add Chargebee webhooks with a custom consumer.
No. Chargebee states that edits made to fields on Salesforce pages are not synced to Chargebee. Use the Chargebee actions instead, such as Change Subscription or Cancel Subscription. The account is the exception: its data can be pushed with the Create/Update Chargebee Customer action or the Sync with Chargebee checkbox.
Yes. A sync rule lets Chargebee create the subscription when an opportunity is won, or upgrade or renew an existing one when the opportunity is for an existing subscription. Products come from the opportunity's Chargebee products, so add them with Manage CB Products and test the rule in a sandbox before enabling it in production.
Chargebee holds a price per billing frequency and currency, but Salesforce allows one price book entry per currency, so Chargebee does not update price book entries after setting them. Current prices are in the CB Item Price object. Use Manage CB Products on opportunities, which fetches live Chargebee prices, rather than the standard Add Products button.
Not in the same org. Chargebee's CPQ integration is a separate package, currently in early access, that needs Salesforce CPQ version 242.2 or higher, and Chargebee states it cannot run at the same time as the standard Chargebee Salesforce integration. Choose one based on where your reps build quotes.
It depends on the catalog, the data and the number of systems involved. In our published quote-to-cash case study, connecting Salesforce, Chargebee and PandaDoc took about 10 weeks in five phases. A full Chargebee implementation with migration typically runs 8 to 12 weeks for a single entity and 3 to 6 months for complex setups.
