Migrate from Chargebee to Lago

Migrate from Chargebee to Lago: what the move involves

If your Chargebee renewal, pricing change or data residency requirement has pushed you toward self-hosting, the move is a staged project: export customers, subscriptions and invoices, rebuild plans and usage metrics in Lago, keep card tokens with a separate payment processor, and run both systems in parallel through at least one full billing cycle. Lago calculates what to charge and when, then hands the charge to a gateway, so the payment side is never a simple lift-and-shift. Most teams hand the work to internal billing and finance engineering, with an implementation partner brought in to fix the scope and plan the cutover. The first decision is the gateway. Lago's FAQ states that you need a separate payment processor, and its README names Stripe, Adyen and GoCardless as supported providers. Card tokens cannot simply be copied across: confirm with your current gateway whether it will move the vaulted payment methods to a PCI compliant receiver, and what format and timeline it requires. Plan the rebuild of plans, add-ons and usage metrics in a non-production Lago instance, and check every rate, proration and tax rule against Chargebee invoices for the same customers before anything goes live.

The parallel run is where most of the risk sits. During it, Chargebee and Lago must not both collect from the same customer, so decide early which system owns collection for each subscription and how renewals are switched. Pin the Lago release to a tagged version rather than the latest image, as Lago's self-hosting docs recommend, and test upgrades before production. Ask your team and your partner to agree in writing on the reconciliation checks, the rollback point and who signs off the cutover. Effort and duration depend on plan complexity, the number of usage metrics and how many accounting and CRM integrations you run, so ask for a scoped estimate from the written scope rather than relying on a general figure.

Which Chargebee capabilities map to Lago, and which need rework

This table maps the main Chargebee capabilities to their Lago equivalents and marks each row as clean, needs rework, or gap. Use it to scope the migration: clean rows can move with data export and re-import, rework rows need rebuilt configuration or code, and gap rows need a decision before cutover. Anything the supplied Lago material does not document is marked for confirmation with Lago and in your own test environment.

Chargebee capability	Lago equivalent and status	What to confirm before migrating
Plans, add-ons and subscriptions	Clean: Lago models plans, charges and subscriptions for recurring billing. Rebuild each Chargebee plan as a Lago plan rather than copying identifiers.	Confirm how proration, trial periods and mid-cycle plan changes behave for each of your plan types in a test tenant.
Usage metering	Needs rework: Lago meters usage events and applies pricing. Event payloads and metric definitions must be rebuilt from your Chargebee usage configuration.	Confirm event ingestion volumes. ClickHouse is an optional external store for high-volume events and is disabled by default.
Invoicing and PDFs	Needs rework: Lago produces invoices and PDFs through its Gotenberg service. Invoice numbering, templates and branding need to be matched to your legal requirements.	Confirm that historical Chargebee invoices stay in Chargebee or an archive, and that new numbering does not collide with old numbers.
Payment collection	Needs rework: Lago calculates what to charge and when, then sends the charge to a payment gateway. Stripe, Adyen and GoCardless are named as supported providers.	Card tokens stay with your existing gateway. Confirm the gateway connection and token reuse path with the gateway before cutover.
Accounting integrations	Needs rework: Lago's README lists NetSuite, Xero, Salesforce and HubSpot integrations. Chargebee accounting connectors must be checked one by one.	Confirm each accounting connector you use against Lago's current documentation, and confirm ledger mapping with your finance team.
Tax calculation	Gap in supplied material: Lago's supplied facts do not describe a tax engine.	Confirm with Lago how tax is calculated and whether an external tax service is needed, and how Chargebee tax settings will be reproduced.
Dunning and failed payment retries	Gap in supplied material: the supplied Lago facts do not describe a dunning or retry feature.	Confirm retry schedules, dunning emails and grace periods in Lago, or plan an external process before cutover.
Revenue and retention modules	Gap in supplied material: Lago's supplied facts do not describe Chargebee's revenue recognition or retention modules.	List which Chargebee modules you use, then confirm equivalents with Lago or plan an external replacement.
Webhooks and events	Needs rework: Lago emits events for its own workflows, so downstream systems that consume Chargebee webhooks must be re-pointed and retested.	Confirm event names, payload shapes and retry behavior in Lago's documentation, and test each consumer in parallel.

Which data moves, through which documented export path

A Chargebee to Lago move carries billing records, not card data. Inventory five entities, then rebuild the accounting and payment links as separate integrations, since each one has its own configuration and test cycle.

Customers and billing profiles

Customer records include names, billing addresses, tax details and external identifiers that Lago will use to map invoices to accounts. Chargebee documents entity-by-entity exports as zipped CSV files and through its API, so export the customer entity first and keep the Chargebee customer ID as an external reference. Check that duplicate or archived customers are resolved before import, because each duplicate will produce a second billing account in Lago.

Subscriptions and billing periods

Subscriptions carry the plan, start date, current billing period, trial end and any scheduled change. Map each active subscription to a Lago subscription with the same anniversary date, so the next invoice is not reset or double counted. Inventory cancelled and paused subscriptions separately, because they affect historical reporting but should not generate new charges.

Invoices and credit balances

Historical invoices are the audit record for revenue and tax, so export them with their line items, taxes and credit notes, and keep the Chargebee invoice numbers as references. Open invoices and unapplied credits need a decision: either settle them in Chargebee before cutover or carry the balance into Lago with a documented opening entry. Ask your finance team which periods the accounting system must reproduce.

Plans, add-ons and usage metrics

Chargebee plans, add-ons and metered components have no automatic equivalent in Lago. Rebuild each plan, charge model and billable metric by hand, then test each one against a sample of real subscriptions before cutover. Usage events are the hardest part: decide whether historical usage stays in Chargebee for reporting, and confirm which events Lago will ingest from the first day of the new cycle.

Accounting integration (NetSuite, Xero)

Lago's README lists integrations with NetSuite, Xero, Salesforce and HubSpot. Treat the accounting link as its own integration: map Lago invoices, payments and customers to your ledger accounts, tax codes and item codes, and run a test sync against a sandbox ledger. Confirm which connector version your ledger and Lago release support before you turn off the Chargebee sync.

Payment gateway connection (Stripe, Adyen, GoCardless)

Card tokens stay with the gateway that holds them, so Lago connects to the same processor rather than receiving card data from Chargebee. Lago's FAQ states that it calculates what to charge and when, then sends that to a payment gateway, and its README names Stripe, Adyen and GoCardless. Confirm that your gateway account, webhooks and customer mapping are configured in Lago and that payment methods still resolve for existing customers before the first Lago-run charge.

How card tokens stay with your existing gateway

Lago does not hold card data, so your cards can stay where they already are. Lago calculates what to charge a customer and when, then hands that charge to a separate payment gateway. Its documentation names Stripe, Adyen and GoCardless as supported providers. The practical question for this migration is therefore not whether Lago can store cards, but whether the gateway that currently holds your vaulted payment methods can be linked to new Lago customers without the cards being exported. Confirm this with that gateway before you design the cutover. Ask whether its stored payment methods can be referenced by a customer identifier from another billing system, whether that reference works through the gateway's own API or through Lago's provider integration, and whether any re-authorization or customer consent step is required.

Treat card export as a separate project with its own scope. Moving raw card numbers to a third party is a PCI-scoped activity, and it usually involves a receiving provider that is itself compliant, encrypted transfer files, and a gateway-side approval step. Vendors describe this in their own terms. Spreedly's export documentation is one example, describing single card exports and encrypted batch files, with processing that can take up to about two weeks. Use such documents only to learn what questions to ask. Your gateway and your assessor will define what applies to you. Ask the gateway for its export policy, the receiving-party requirements, timelines and any fees, and involve your QSA or compliance lead before any card data leaves the vault.

Plan for the possibility that some customers will need to re-enter payment details. Where the gateway token cannot be reused, you may have to request card updates from customers at their next invoice, which affects dunning, failed payment rates and revenue timing. Decide this early and record it in the cutover plan, including which customers are affected, how they are notified and which invoices fall back to manual collection during the parallel run.

The migration sequence from inventory to decommission

This sequence moves subscription billing from Chargebee to a self-hosted Lago instance in controlled stages, with each stage producing a document or check that the next one depends on. Card tokens stay with your existing payment gateway throughout, so billing logic moves without moving card data.

Inventory plans, gateways and integrations
Your billing lead and finance operations lead list every active plan, add-on, coupon, usage metric, tax setting, dunning rule and webhook, along with each payment gateway that holds card tokens and every accounting or CRM connection that consumes invoices. Include the gateway account IDs and the Chargebee entities that depend on them. The output is an inventory document signed by both teams, which defines the scope of everything that follows.
Stand up a pinned Lago pilot
Platform engineering deploys Lago with Docker Compose in your own infrastructure, pinning the last tagged release rather than the latest image tag, as Lago's self-hosting documentation recommends. The team confirms the front end, API, workers, PostgreSQL, Redis and Gotenberg are healthy and that backups and access controls are in place before any customer data arrives. Larger deployments should evaluate the Helm charts and dedicated workers described in the same documentation. The pilot is done when a test customer can be created, subscribed and invoiced end to end.
Map plans, metrics and customer records
Billing engineers translate each Chargebee plan, add-on, charge model and usage metric into a Lago plan, billable metric and charge definition, and record every field that does not map cleanly, such as proration behavior, trial handling or tax rules. They also define how Chargebee customer and subscription identifiers will be stored as external IDs in Lago. The output is a mapping document that finance has reviewed line by line, with each gap assigned an owner and a decision.
Import data and reconcile a sample
Engineers export customers, subscriptions and invoices from Chargebee as CSV or through its API, load them into the pilot Lago environment with scripts, and then compare a sample of accounts field by field against the source. Totals, balances, billing anchors and open invoices must match. Card tokens are not part of this import: the gateway keeps them, and Lago is connected to that same gateway so it can charge them. The output is a reconciled sample report that lists every mismatch and its resolution.
Run both systems through a full billing cycle
For at least one complete billing cycle, Chargebee continues to issue the invoices customers receive while Lago calculates the same charges in parallel on the same usage data. Finance compares each generated invoice line by line, investigates every variance, and tracks which system is the source of record for payment collection. The output is a signed-off invoice comparison covering the full cycle, with variances explained and fixed in the mapping before cutover.
Define the freeze and write the cutover runbook
The project lead agrees a billing freeze window with finance, sales operations and support, during which no plan, price or subscription changes are made in Chargebee. The runbook lists the final export, the final delta import, the order of webhook and integration switches, who approves the go-live decision and the rollback path back to Chargebee if a critical issue appears. The output is a cutover runbook that the named owners have rehearsed at least once against the pilot environment.
Cut over and monitor the first cycle
On the agreed date, the team completes the final export and delta import, switches the gateway webhooks and accounting integrations to Lago, and confirms the first live invoices and payment attempts. Support monitors failed payments, dunning and customer questions closely through the first cycle. The output is a cutover record with timestamps, the first-cycle reconciliation results and a list of open issues with owners.
Decommission Chargebee and archive exports
Once the first live cycle reconciles and open issues are closed, the team disables Chargebee webhooks and integrations, confirms with the gateway that no duplicate subscriptions remain, and retires access for former administrators. Before the account is closed, the team archives complete exports of customers, subscriptions, invoices and the mapping and reconciliation documents in encrypted storage under your retention policy. The output is a decommissioning record and an archive index that auditors and finance can retrieve later.

What drives migration cost and duration

This table lists the factors that most affect the effort and calendar time of moving Chargebee billing to Lago, with the reason each one matters and how to keep it under control. Read it before scoping, because the largest cost usually comes from catalog complexity and the parallel run rather than from the software itself.

Driver	Why it changes cost or effort	How to keep it down
Catalog complexity	Every plan, add-on, coupon and usage metric must be rebuilt as a Lago plan, charge and billable metric, and each mapping needs testing against real invoices.	Retire unused plans and metrics before migrating, and map the catalog to a short written list of Lago objects with one owner per item.
Active subscriptions and invoice history	Migrated subscriptions need correct billing anchors, proration and balances, and the volume of history drives import runtime and reconciliation work.	Migrate active subscriptions only, keep closed history in exports for reference, and reconcile totals per customer before cutover.
Usage metrics and event volume	Usage-based charges depend on event streams that must be replayed or aligned at the cutover date, which can be the hardest part of the rebuild.	Set one cutover timestamp for usage, confirm how partial periods are billed in both systems, and decide early whether ClickHouse is needed for event volume.
Payment gateway integration	Lago does not hold card data and needs a supported processor such as Stripe, Adyen or GoCardless. Connecting it to the gateway that already holds your tokens is a separate integration task.	Confirm with the gateway that existing tokens can be used by the new billing system before scoping, and test a charge in staging before cutover.
Accounting and CRM integrations	Invoices and customer records feed NetSuite, Xero, Salesforce, HubSpot or other systems. Each feed must be remapped and its historical entries checked for duplicates.	List every downstream consumer of Chargebee data, map each one to a Lago integration or export, and test ledger totals for one full period.
Tax and dunning rules	Tax settings, invoice numbering, retry schedules and reminder emails are often configured by hand in Chargebee and must be re-specified and tested in Lago.	Document current tax and dunning settings from the Chargebee admin before migration, and get tax rules signed off by finance and tax advisers.
PCI scope of card handling	If card data is exported or re-entered, the organization may take on new PCI DSS obligations. Keeping tokens with the existing gateway keeps card data out of the migration.	Keep card tokens with the gateway, avoid manual card exports, and ask your QSA to confirm the scope of the new architecture before cutover.
Internal skills and ownership	Someone must run Lago's PostgreSQL, Redis, workers and PDF generation, and the team must understand billing logic. Gaps in skills extend the timeline and raise run risk.	Name owners for billing, infrastructure and finance reconciliation before scoping, and plan knowledge transfer or a support retainer for the first billing cycles.
Length of the parallel run	Running Chargebee and Lago side by side through at least one full billing cycle is the main driver of calendar time, and it doubles some operational work during that period.	Agree the parallel run length and exit criteria in writing at the start, compare invoices line by line each cycle, and stop Chargebee writes only after sign-off.

How the move differs by starting point

A small SaaS with a handful of plans and Stripe as its payment processor usually has the smallest migration scope. Lago calculates what to charge and when, then hands the charge to Stripe, so the card tokens already held by Stripe can stay where they are. The work centers on rebuilding a short plan list, confirming tax and invoice numbering, and connecting the accounting tool the team uses.

Scope: Recreate a small set of plans, add-ons and coupons in Lago, and map existing subscriptions to them.
Card tokens: Keep them with Stripe and connect Lago to the same Stripe account, so customers do not re-enter cards.
Parallel run: Usually one full billing cycle, with Chargebee still issuing invoices while Lago computes the same amounts in shadow mode.
Sign-off: Finance compares invoice totals and tax lines for every subscription before the cutover date.
Self-hosting: The Docker Compose deployment described in the Lago self-hosted docs is generally enough at this size, and it runs the API, workers, PostgreSQL and Redis on one set of services.

Confirm with your team whether your Stripe account is the same one Chargebee uses, because switching accounts changes how subscriptions and card tokens are referenced.

What usually goes wrong and how to prevent it

Most failed billing migrations break in the same few places: the parallel run, the mapping of plans and usage, the history, the integrations and the gateway. The cards below pair each failure with a check you can run before cutover, and they assume Chargebee and Lago run side by side for at least one full billing cycle.

Double billing during the parallel run

Chargebee and Lago both hold active subscriptions while you test, so a customer can be charged by each system for the same period. Pick one system as the only charge originator for every subscription before the first Lago invoice runs, and disable automatic collection in the system you are leaving. Reconcile each billing run against the gateway's charge list, not only against invoice totals.

Mismatched plan and usage mapping

Chargebee plans, add-ons and charge models rarely map one to one onto Lago plans, billable metrics and charges. A metered add-on that rounds differently, or a tiered price with a different boundary, shifts the amount on every invoice. Build a mapping sheet, then rate the same sample usage events in both systems and require identical totals before any customer moves.

Lost invoice and credit history

Migrated subscriptions often start with a blank invoice history, which breaks customer statements, tax records and refund references. Decide which historical invoices, credit notes and balances to import as records, and which to keep only in a read-only Chargebee export. Confirm with your accountant that every legal invoice number still resolves to a document you can produce on request.

Broken webhooks and dunning

Payment events, failed-charge retries and dunning emails depend on webhooks that point to the old system. If a webhook endpoint is missing from Lago or a failed-payment event is not handled, customers stop being chased for money or receive duplicate reminders. Map every Chargebee webhook event to its Lago equivalent, register the Lago endpoints with your gateway, and test a declined card end to end.

Gateway token mismatch

Lago does not store card data. It calculates what to charge and sends that to a payment gateway such as Stripe, Adyen or GoCardless, so the saved card must already be linked to a customer ID that the gateway and Lago both recognize. If the customer identifiers or payment method references differ, charges fail or attach to the wrong customer. Confirm that each token survives the move with your gateway before you change any customer record.

Running an unpinned image

Lago's self-hosting guidance recommends pinning the last tagged version rather than the latest image tag. An unpinned deployment can pull a different release during a restart or redeploy, changing behavior between your test and production environments. Record the exact tag you validated, deploy only that tag, and schedule upgrades as planned changes with a test run first.

Underestimating the billing team

Running Lago means someone owns the billing rules, the worker health, database backups and upgrades, and the reconciliation that finance relies on. Teams often plan the migration as a technical task and discover in the first month that nobody is accountable for failed jobs or price changes. Name an owner, a backup owner and a runbook before cutover, and confirm the on-call coverage you need with your own staff or support provider.

Questions buyers ask before moving from Chargebee to Lago

How much effort and cost does moving from Chargebee to Lago involve?

The cost depends mostly on how many plans, add-ons, usage metrics and integrations you have, and on how clean your Chargebee data is. Lago's software can be used under its free open-source edition or an Enterprise plan, so the software license is one line item among several. The recurring costs are servers, PostgreSQL, Redis, your payment gateway fees (which stay the same either way), and the people who operate billing. One-time costs include the migration work, rebuilding the catalog in Lago, testing, and documentation. Ask any provider for a quote that lists these components separately, with the assumptions behind each one, so you can compare it with your current Chargebee spend.

How long does a Chargebee to Lago migration take?

The timeline is set by the number of catalog objects to rebuild, the volume of historical data you need, how many integrations must be reconnected, and whether you want a full billing cycle of parallel running before cutover. Most teams plan the work around a billing cycle, because the safest point to switch is the start of a new cycle with both systems reconciled. Ask for a written timeline tied to a defined scope, with named milestones for the export, catalog rebuild, test billing runs, parallel run and cutover. Treat any duration quoted without that scope as incomplete.

What does the migration need from our finance and engineering teams?

Finance owns the business rules that must survive the move: plan prices, proration behavior, tax treatment, credit notes, dunning steps and revenue recognition inputs. They also need to approve reconciliation between Chargebee and Lago invoices before cutover. Engineering owns the data export, the mapping of customer and subscription identifiers, the Lago API calls, webhook handling, usage event pipelines and the gateway connection. Both teams should agree early on a single source of truth for each object and on who signs off each test cycle. Expect engineering time to be concentrated in the build and parallel-run phases, and finance time to peak during reconciliation.

Can we run the Chargebee to Lago migration without outside help?

Yes, if you have engineers who can work with billing APIs, a finance lead who can own the reconciliation, and time to test thoroughly. Lago's documentation and self-hosted guides cover the deployment, and the open-source project is public for review. Teams without recent billing migration experience often underestimate reconciliation, edge cases such as mid-cycle changes and refunds, and the operational load of running billing workers, queues and PDF generation. An outside implementation partner can take on a fixed scope, such as the deployment, catalog mapping or parallel-run testing, and document the results. Decide which parts you will keep in house before you ask for a quote.

Do card details move from Chargebee to Lago?

Card data does not have to move from Chargebee to Lago, and in most setups it should not. Lago calculates what to charge and when, then sends that charge to a payment gateway. Lago's documentation names Stripe, Adyen and GoCardless as supported providers, and the gateway is what holds the card tokens. Your existing gateway can keep the stored payment methods, and Lago references them through its gateway connection. Confirm with your gateway how its tokens can be reused by a new billing system, and whether the tokens belong to your merchant account or to Chargebee's integration. Where a token export is needed, ask the gateway for its documented export process and timelines, and plan for it early.

Does Lago's free edition cover our features, or do we need Enterprise?

Lago offers a free open-source edition with fundamental billing features and Enterprise plans that add premium features. Whether the free edition is enough depends on which capabilities you use in Chargebee today. Compare your plans, usage metering, invoicing, tax handling, and accounting integrations against Lago's current feature documentation, and list any Chargebee module you rely on, such as revenue or retention tooling, that Lago may not cover in the same way. Lago's README lists integrations with NetSuite, Xero, Salesforce and HubSpot, so check whether your accounting or CRM tools are among them. Ask the vendor to confirm in writing which features require the Enterprise plan before you build the plan.

How does a parallel run avoid double billing customers?

A parallel run avoids double billing by making sure only one system is allowed to charge a given customer at any time. During the run, Lago should calculate invoices in test or shadow mode while Chargebee remains the system that collects payment. Each cycle, you reconcile Lago's calculated invoices against Chargebee's, including amounts, taxes, proration and usage totals, and resolve every difference before cutover. Cutover should happen at a defined boundary, with Chargebee subscriptions stopped or moved so that no customer receives two charges for the same period. Keep Chargebee available in read-only mode for refunds and audit requests. Ask any provider to show the reconciliation report and cutover checklist as part of the scope.

How DeployOpen scopes, runs and supports the move

DeployOpen is a Chainscore Labs company that plans, implements, integrates, hardens, backs up and documents self-hosted Lago inside your own cloud account, data center or air-gapped network. The move from Chargebee is scoped in writing before any work starts, and the written scope names the parts of the migration that are in and out: the Lago deployment, the plan and metric rebuild, the import of customers, subscriptions and invoices, the connection to the gateway that already holds your card tokens, and the parallel-run period. Most engagements are fixed-scope, so the scope document, deliverables and timelines are agreed with your billing, finance and security owners before a single environment is provisioned. Ask the team to show which Chargebee exports they expect to use and which Lago components they will deploy, so that the scope reflects your actual data and not a generic template.

DeployOpen does not publish a price list. A quote follows from the written scope, so the fastest way to get a meaningful number is to bring a complete inventory of your plans, add-ons, usage metrics, coupons, tax rules, accounting integrations and gateways. Ask for the quote to separate one-time work (discovery, the rebuild, the import scripts, hardening and the parallel-run reconciliation) from recurring items (hosting you pay your cloud provider for, Lago Enterprise licensing if you choose it, and any retainer). Confirm with Lago whether your needs fit the free open-source edition or require Enterprise features, because that choice changes the scope.

Once the migration is live, ongoing support, upgrades and continuous testing are available as retainers. This matters for Lago in particular: its self-hosting documentation recommends pinning the last tagged release rather than the latest image, so someone must own version pinning, release review and the upgrade calendar. Agree in writing who receives alerts from the clock and API worker processes, who restores PostgreSQL backups, and who signs off on a Lago upgrade before it reaches production billing. DeployOpen documents each of these items as part of the handover, so your team can run the system after the engagement or keep DeployOpen on a retainer for the upgrade cycle.

Migrate from Chargebee to Lago