Integration architecture in a subscription stack is not really about transport. It is about ownership: which system is authoritative for each attribute, what happens when two of them disagree, and how you find out that they have. This guide is the reference we design against — the ownership matrix, the topology patterns, and the anti-patterns.
Trusted by 500+ organizations — including SaaS, subscription and usage-based businesses running their quote-to-revenue operations on Salesforce, HubSpot and Chargebee with Twopir Consulting.
Architecture Coverage
A subscription stack has at least five systems holding overlapping views of the same customer. Architecture is the discipline of deciding, in advance, which view wins.
Chargebee integration architecture is the set of decisions that determine how Chargebee, the CRM, the product, the ledger and the payment gateway share one commercial reality: which system is authoritative for each attribute, how changes propagate between them, how conflicts are resolved, and how divergence is detected.
The transport mechanism — connector, iPaaS, webhook consumer, batch job — is a downstream choice. Picking it first is the most common architectural mistake in this stack, because every transport can be made to work and none of them can compensate for an ownership model that was never agreed.
| Principle | What it means in practice | The failure it prevents |
|---|---|---|
| One owner per attribute | Every field has exactly one authoritative system. Others hold read-only copies, explicitly labelled as such. | The last-write-wins race, where two systems overwrite each other and both teams stop trusting the record. |
| Own by lifecycle stage, not by system | The CRM owns commercial intent up to closed-won; Chargebee owns everything about the live subscription afterwards. | Arguments about whether 'the CRM' or 'billing' owns a customer, which have no answer at that altitude. |
| Events describe facts, not instructions | A webhook says a subscription changed. The consumer decides what that means in its own domain. | Brittle coupling where a change in one system's internal model breaks three others. |
| Assume at-least-once delivery | Every consumer is idempotent on event id. Duplicate delivery is normal operation. | Double provisioning and duplicate charges, which is the single most common production billing bug. |
| Reconcile continuously | A scheduled comparison of counts, totals and states between systems, with alerting on variance. | Silent drift discovered months later by finance, with no way to date the divergence. |
| Design for the next pricing model | Mappings expressed against catalog concepts rather than specific plan names. | An integration that is correct for a commercial model you stopped selling last year. |
This is the artefact we produce first on every integration engagement. Your matrix will differ in places — the point is that it exists and is agreed, not that it matches this one exactly.
| Attribute | Authoritative system | Who holds a read-only copy, and why |
|---|---|---|
| Account identity and hierarchy | CRM | Chargebee, so invoices carry the right legal entity and parent-child billing works. |
| Commercial intent before close | CRM | Nobody. Pipeline, forecast and negotiation belong in one place until the deal closes. |
| Product catalog and price points | Chargebee | CRM, as Products and Price Book Entries, so quoting uses real prices rather than a parallel list. |
| Subscription state, plan and quantity | Chargebee | CRM and product, so the rep sees the live plan and the app enforces it. |
| Billing anniversary and term dates | Chargebee | CRM, for renewal pipeline and forecasting. This is the field most often contested, and the CRM should not win it. |
| Entitlements and feature access | Chargebee | Product, which reads entitlements rather than inferring access from plan names. |
| Usage and consumption | Product | Chargebee, aggregated into billable units by metered features. |
| Invoices, credit notes and payments | Chargebee | CRM for context, ledger for accounting. Never edited anywhere but the source. |
| Payment instruments | Gateway vault | Chargebee holds the token reference only. Card data lives in the vault, nowhere else. |
| Recognised revenue | RevRec, posting to the ledger | The ledger is authoritative for the financial statements; the subledger explains them. |
| Tax determination | Tax engine, such as Avalara | Chargebee stores the determination on the invoice as an immutable record of what was applied. |
The engagements that implement this architecture are Chargebee integration services — integration services, connector-first Chargebee API and integration development — and custom development where code is genuinely needed Chargebee migration guide — plus the migration guide if you are moving platforms Chargebee consulting services — all of it inside the wider Chargebee practice
Most stacks use all three in different places. The mistake is choosing one as a standard and forcing every flow through it.
Each system connects to each other system it needs. Simple at two or three systems, and the supported connectors are exactly this shape done well. Complexity grows quadratically, so it stops scaling quietly rather than obviously.
Every system connects once to an iPaaS which routes and transforms. Adding the fourth and fifth systems is cheap, error handling is uniform, and a non-engineer can see what is failing.
Chargebee publishes events; interested systems subscribe independently. Adding a consumer changes nothing upstream, which is the property that matters most as the stack grows.
| Flow | Recommended pattern | Why |
|---|---|---|
| CRM to billing on closed-won | Point-to-point via the supported connector. | Well-defined, vendor-maintained, and the mapping is stable across pricing changes. |
| Billing to CRM subscription state | Point-to-point via the same connector. | One-directional, read-only at the destination, no conflict surface. |
| Billing to product provisioning | Event-driven. | Latency matters, the logic is yours, and the consumer can evolve independently. |
| Product usage to billing | Batch or streamed pipeline, owned by you. | Volume, aggregation and late-arriving events need logic no connector provides. |
| Billing to ledger | Connector or scheduled batch. | Accounting is periodic by nature. Real-time posting adds risk and no value. |
| Anything crossing three or more systems | Hub and spoke. | Uniform error handling and one place to change logic beats three bespoke links. |
Distributed systems diverge. An architecture is judged by how quickly it notices and how cheaply it repairs, not by whether divergence ever happens.
De-duplicate on event id with a retention window covering the full retry period. Chargebee retries a failed webhook with increasing delays for up to two days, up to seven times, so duplicate delivery is a design input rather than an exception.
Every create or charge request carries an idempotency key, so a client-side retry after a timeout cannot produce a second subscription or a second charge. A replayed request is flagged as such in the response.
Events can arrive out of order. Consumers compare a resource version or timestamp from the payload against what they already hold, rather than trusting delivery sequence.
A message that cannot be processed goes to a queue with its payload intact and an alert attached. Acknowledging a failure to stop retries is how a week of missing events becomes a reconciliation project.
A periodic comparison of subscription counts, invoice totals, MRR and state between systems, alerting on variance. This is the control that converts silent drift into a report somebody reads.
Raw events stored and tooling to reprocess a time range. When something was wrong for a week, correction should be a documented operation rather than a script written under pressure at month end.
Each of these is something we have been called in to unwind. They are listed with the replacement rather than just the criticism.
| Anti-pattern | Why it fails | What to do instead |
|---|---|---|
| Bi-directional sync on a contested field | Two writers, no arbiter. The last write wins and both teams lose confidence in the record. | One owner, one-directional flow, and a read-only copy labelled as such at the destination. |
| Billing logic re-implemented in the product | Proration and price calculation drift apart from the billing system on every pricing change. | Read entitlements and prices from the billing record. Let one system own the arithmetic. |
| Processing the webhook synchronously | Slow downstream work causes a timeout, which causes a retry, which causes duplicate work. | Store the event durably, acknowledge with a 2xx immediately, process from a queue. |
| Polling instead of subscribing | Wasteful at low frequency and still latent at high frequency, while the platform already publishes the event. | Consume webhooks. Reserve polling for reconciliation sweeps, not for state propagation. |
| Plan names as the integration contract | Every new plan or packaging variant requires code changes in every consumer. | Map against catalog concepts — entitlements, product families, item price attributes — not string identifiers. |
| No environment separation | Testing against the live site, or a test site whose catalog has diverged from production. | A test site kept structurally aligned with production, refreshed on a schedule and used for every change. |
| Reconciliation by exception report only | Only detects the failures you predicted. The expensive ones are the categories nobody anticipated. | Compare totals and counts as well as exceptions, so an unexplained variance surfaces even without a known rule. |
| One integration owner with no documentation | The architecture leaves when the person does, and the next change is made by someone reverse-engineering it. | A written ownership matrix, documented interfaces and a runbook, maintained as part of delivery. |
Most subscription architectures are designed for the business as it is and quietly assume it will stay that shape. These are the four expansions that break that assumption, and what to decide in advance.
Affects invoice numbering, tax determination, the catalog and the ledger mapping all at once. Decide the entity model before go-live; retrofitting one is a rebuild rather than a configuration change.
Price points are per currency, and reporting has to decide whether it normalises at transaction rate or period rate. Both are defensible; only one can be the answer, and it should be written down.
Product families and entitlement structures have to distinguish them without duplicating the whole catalog. This is where a flat catalog design shows its age.
Introduces a pipeline, a reconciliation obligation and volatility in revenue reporting. It is the single largest architectural change most subscription businesses make after go-live.
Designing the ownership and consistency model across connected commercial systems is the core of Twopir's architecture work.
Two overlapping systems of record reconciled with an explicit ownership model, sync direction and conflict rules rather than a bidirectional sync on defaults.
A multi-system topology designed around the quote-to-fulfilment flow, with data contracts agreed between systems before anything was built.
Financial and operational systems connected with reconciliation designed into the architecture rather than bolted on at close.
We help growing and mid-market companies solve complex CRM, integration and business system challenges, and we design the same architectures for enterprise teams across more entities, products and markets.
Before any connector is chosen, every attribute gets exactly one authoritative system. It is an unglamorous document and it is why the architectures we design are still correct two pricing models later.
Point-to-point for CRM to billing, event-driven for provisioning, batch for the ledger, hub and spoke once four systems are involved. A single mandated pattern is a preference, not a decision.
Scheduled comparison of counts, totals and states with alerting, plus a replay path. Divergence is inevitable in a distributed stack; being unable to detect it is a design choice.
As a Salesforce Partner and HubSpot Partner we design and build both sides. The seam between two vendors is where most integration defects live, and the cheapest fix is to remove the seam.
Ownership matrix, interface contracts, failure behaviour and a runbook, maintained as part of delivery. An architecture that lives in one person's head is a dependency with a notice period.
No single one, which is why the question causes so much argument. Ownership is assigned per attribute and per lifecycle stage: the CRM owns commercial intent up to closed-won, Chargebee owns everything about the live subscription afterwards, the product owns usage, the ledger owns recognised revenue, and the gateway vault owns payment instruments. Trying to nominate one system as the source of truth for everything is the argument that never resolves.
For most fields, no. Bi-directional sync on a contested field is a race where the last write wins and both teams eventually stop trusting the record. The workable pattern is directional by lifecycle stage — the CRM writes to billing at closed-won, billing writes subscription state back for reporting, and the destination copy is read-only and labelled as such.
Chargebee. It is the most frequently contested attribute in this stack and the CRM usually wins the argument politically, which is the wrong outcome. The renewal date is derived from the term and the billing cycle, both of which live in billing, and a CRM edit to it does not change what the customer will actually be invoiced.
Per flow. Event-driven where latency matters and the logic is yours — provisioning, entitlement enforcement, anything the customer experiences immediately. Batch where the destination is periodic by nature, which is most accounting and ledger work: real-time posting to the GL adds operational risk and no business value. Usage pipelines are usually a hybrid, streamed in and aggregated on a schedule.
By scheduling a comparison, because nothing else will tell you. A periodic reconciliation of subscription counts, invoice totals, MRR and subscription state between systems, with alerting on variance. Compare totals and counts as well as known exception rules — exception-only reporting detects the failures you predicted and misses the expensive ones nobody anticipated.
Roughly at the fourth system. Below that, point-to-point connections and the supported connectors are cheaper and simpler. Above it, point-to-point complexity grows quadratically while hub-and-spoke grows linearly, and you also get uniform retry handling, error visibility and a place to change logic without a deployment. The licence is usually cheaper than the third bespoke integration.
At minimum: the ownership matrix, the interface contract for each flow — events consumed, calls made, failure behaviour — the idempotency strategy and its retention window, the reconciliation schedule and what it compares, and a runbook covering replay and failure recovery. Architectures that exist only in one engineer's head are dependencies with a notice period.
We will review your current topology, produce the ownership matrix, choose the right pattern per flow and design the reconciliation — then build it across Chargebee and the CRM with one team.
Guide last reviewed September 2026 — re-verify platform specifics before relying on them
