How to export your data from Chargebee

How to export your data from Chargebee without losing billing history

Chargebee lets you export billing entities as zipped CSV files or through its API, but card data does not come out with them. Card tokens stay with the payment gateway that holds them, so a move away from Chargebee depends on what that gateway allows. Before you schedule anything, confirm in Chargebee's own documentation which entities, formats and export options your plan includes, and how long generated export files remain available for download. Record those answers in your migration plan, because the export window may be shorter than your cutover timeline.

Core records such as customers, subscriptions, invoices and plan definitions are the usual starting point for a billing move, but you should verify each entity against your own account rather than assume the set is complete. Usage history, credit notes, custom fields and payment method references need separate checks, since some may appear only in the API or in a different file. Keep full copies of invoices and transaction history for your records and any audit requests. Do not treat the CSV set as a substitute for the archive you may need later.

Plan the gateway step first. Ask your gateway whether stored payment credentials can be transferred to another account or processor, and under what conditions. If transfer is not possible, customers must re-enter cards, which changes your renewal and dunning plan. Lago, for example, calculates what to charge and then sends the charge to a separate gateway, so the processor decision comes before the data import. Once the gateway path is settled, export billing data, import it into the target system in a test environment, and reconcile balances before moving live billing.

Which Chargebee entities can you export, and in what format

This table lists the Chargebee entities to include in your export inventory, how each one leaves the platform, and what the resulting file is expected to hold. Use it as a checklist before you move anything. Availability windows, pagination and file size limits can change, so confirm them on Chargebee's current export page and in the API reference before you set a migration timeline.

Entity	Export method	Format	What the file holds
Customers	Dashboard or API	Zipped CSV from dashboard; API responses per API reference	Customer IDs, names, contact details, billing addresses and linked gateway references
Subscriptions	Dashboard or API	Zipped CSV from dashboard; API responses per API reference	Plan, status, billing cycle, term dates and attached add-ons
Plans and add-ons	Dashboard or API	Zipped CSV from dashboard; confirm API coverage	Item prices, billing periods, currencies and tier structure; confirm how tiered and usage pricing appears
Invoices	Dashboard or API	Zipped CSV from dashboard; confirm whether line items export separately	Invoice numbers, totals, taxes, status and dates; line-item detail may need its own file
Credit notes	Dashboard or API	Zipped CSV from dashboard; confirm API coverage	Issued amounts, linked invoices and refund status
Transactions	Dashboard or API	Zipped CSV from dashboard; confirm API coverage	Payment attempts, outcomes, dates and gateway transaction IDs for reconciliation
Payment sources	API or gateway export	Confirm format in the export documentation	Masked card details and gateway references; full card numbers stay with the gateway that holds them

What does not come out of Chargebee and how to handle each gap

A Chargebee export gives you records, not everything that makes billing work. The items below sit outside the zipped CSVs or depend on the gateway, so each one needs its own route. Confirm each item against Chargebee's current documentation before you plan the cutover.

Stored card credentials

Card numbers are not in your Chargebee export because they sit with the payment gateway that tokenized them. Whether you can move them depends on that gateway's export or migration path, not on Chargebee. Ask your gateway whether it supports a token or card export to a PCI DSS compliant receiving party, how long that takes, and whether it charges for the file. Until that path is confirmed, plan for customers to re-enter cards on a hosted page.

Gateway customer and payment method references

Chargebee stores the gateway customer ID and payment method ID for each subscriber. These references are useless in Lago or Kill Bill unless the target connects to the same gateway account and can read those objects. Export the mapping from Chargebee, then confirm with the gateway whether the IDs stay valid after a move between systems. If they do not, you will need a re-link step for each customer during cutover.

Catalog logic, coupons and tax settings

Plans, add-ons, price points, coupons and tax rules are configuration, not transaction data. Chargebee's CSV exports list them, but they do not carry the logic that applies them, such as proration rules, coupon stacking or tax overrides. Rebuild the product catalog in the target system and test each plan against a sample of real subscriptions. Compare invoice totals from both systems for the same period before you switch.

Webhooks and integration connections

Chargebee webhooks, accounting sync and CRM connectors are configured inside the Chargebee account. Exporting data does not export these connections, so your accounting, support and data pipelines will stop receiving events when the account closes or is switched off. List every connected system, then reconfigure each one to receive events from Lago or Kill Bill. Test that ledger entries and invoice numbers still reconcile.

Rendered PDF invoices and custom templates

Chargebee generates invoice PDFs from its own templates, and the CSV export does not include those files. Keep the rendered PDFs through the API or your document archive for audit and customer queries. In the target, regenerate invoices from the migrated data using a template that matches your legal and tax requirements, and check that invoice numbering continues without gaps or duplicates.

Where the exported data lands: Lago or Kill Bill

Lago rebuilds the customer, subscription and invoice history you export as plans, billable metrics, subscriptions and invoices in its own data model. Its Docker Compose deployment runs a front end, an API, an API worker, a clock worker, PostgreSQL for application data and Redis as the job queue, with Gotenberg generating PDFs. Lago decides how much to charge and when, then sends the charge to a payment gateway. It does not replace the processor, so Stripe, Adyen or GoCardless must accept your card tokens or customers must re-enter their details.

Customers and subscriptions: Map the customer and subscription exports to Lago customers and subscriptions, and keep Chargebee's identifiers as external IDs so records from both systems can be matched during parallel running.
Plans and usage metrics: Plan and add-on exports must be rebuilt as Lago plans and billable metrics. Usage history is not a direct copy of the plan file, so define each metric before importing usage.
Historical invoices: Keep past invoices as read-only archive files for accounting and dispute handling, and let Lago issue new invoices from the cutover date.
Payment processor: Agree the token transfer with Stripe, Adyen or GoCardless before any import. Lago's README names these providers, but whether your existing tokens can move is a question for the processor.
Accounting and CRM: The README lists NetSuite, Xero, Salesforce and HubSpot integrations. Confirm that the one you use supports the object mapping you need.

Before any import runs, confirm the processor's token position in writing and size and back up the PostgreSQL and Redis hosts.

The order to export and move cards and billing data

This sequence moves customers, payment references, subscriptions and billing history out of Chargebee in an order that keeps card credentials with the gateway and proves the target matches the source before anyone is charged. Each step ends with a check you can record, so the team knows when to move on. Work through the steps in order, because later exports depend on IDs and references created earlier.

Inventory every entity and integration
List every object Chargebee holds for your billing, including customers, subscriptions, plans, add-ons, coupons, invoices, credit notes, transactions and payment sources, and confirm which export Chargebee provides for each. Include the systems connected to billing, such as accounting, CRM, tax, the payment gateway, webhooks and custom fields your team relies on. Assign an owner to each item. The output is a signed-off inventory with record counts per entity, which becomes the baseline for every reconciliation later.
Confirm credential transfer with the gateway
Ask the payment gateway that holds your card tokens whether stored credentials can be exported or transferred to another processor or to a PCI DSS compliant third party, and under what conditions. Confirm the file format, whether the transfer is a single record or a batch file, who must approve it, and what the receiving system must certify. Ask whether the tokens can be used outside the gateway account at all. The output is a written decision on whether cards move, or whether customers re-enter payment details in the new system.
Freeze plan and price changes
Stop changes to plans, add-ons, prices, tax settings and coupons in Chargebee for the duration of the export, and tell every team that edits them. Record the catalog as it stands, including currencies, billing periods and tax configuration, so the target is built from a known version. Set a cutoff time for subscription changes and usage ingestion. The output is a dated catalog snapshot and a documented cutoff, so later exports can be compared to the same state.
Export customers and payment references first
Export customer records and the payment source references linked to each customer. Load them into a working file and check that every customer has a unique identifier, a billing address and a currency, and that each payment reference matches a token you confirmed in the gateway step. Count customers and payment sources, then mark any customer whose card cannot move so it can be collected again. The output is a customer file with a readiness status for each record.
Export subscriptions and check billing dates
Export subscriptions after customers, so each one links to an existing customer ID. Verify the plan, quantity, add-ons, discounts, status, trial end and current billing period for each record. Compare next billing dates and billing anchors with Chargebee for a deliberate sample, including the largest accounts, usage-based plans, coupon users, and paused, cancelled or scheduled-change subscriptions. The output is a subscription file, a matched sample of billing dates and a list of exceptions to resolve.
Export invoices, credit notes and transactions
Export invoices, credit notes and payment transactions, which hold the financial history your accounting team depends on. Confirm that each invoice links to its customer and subscription, that line items and tax amounts are present, and that each credit note references the invoice it reduces. Total the amounts by currency and by period, and compare those totals with Chargebee's own reports. Keep this history as read-only records in the target or in your data store, since it supports audits and disputes. The output is a set of totals by currency and period that match the source.
Load into a non-production target
Load the customer, subscription and history files into a non-production environment of the target billing system. For Lago, deploy a self-hosted instance pinned to a tagged release, as the Lago self-hosting documentation recommends. For Kill Bill, load accounts and subscriptions through its REST APIs into a Tomcat deployment. Connect the gateway in test mode only, and turn off customer email and outbound webhooks. Log every load error against its source ID. The output is a loaded test environment and an error log the team clears before the next step.
Reconcile counts and totals before any charge
Compare the target with the Chargebee baseline from the inventory: record counts for each entity, invoice and transaction totals by currency, the number of active subscriptions, and the billing dates for the sample chosen earlier. Run a dry billing cycle in the target and confirm that the amounts it would collect match what Chargebee would collect for the same subscriptions. Only after every variance is explained and signed off should the new system take live charges, and Chargebee billing should stop in the same change window. The output is a signed reconciliation report.

How to verify an export is complete before you cut over

Do not switch billing until you have reconciled the export against Chargebee itself. Start with entity counts: compare the number of customers, subscriptions, invoices, credit notes and plans in Chargebee's reporting or list views with the record counts in your target system after import. Filter both sides by the same date window and status, and treat any gap as a defect to explain, not a rounding issue. Confirm the counts also cover archived or cancelled subscriptions, because those are the records most often left out of a bulk export and most often needed in a dispute.

Next, reconcile money, not just rows. For each customer, compare the sum of invoice totals, payments received, credit notes issued and remaining credit balance in Chargebee with the same figures in the target. Then check the active subscriptions one by one: each should map to a payment method reference that still resolves at your gateway, which is where the card itself lives. A subscription with no working token will fail at its next renewal, so a sample test charge on a small set of accounts is worth the effort. Finally, run a parallel billing cycle on a sample of accounts, comparing the amounts the new system calculates with what Chargebee would have invoiced, before you move the full base.

Keep the raw Chargebee export files, unchanged and checksummed, as an archive for audit and dispute purposes. Records of past invoices and refunds may be needed long after the cutover, and the target system may format or transform fields in ways that make later comparisons harder. Confirm with your own compliance and legal teams how long billing records, customer correspondence and payment-related data must be retained, where that archive may be stored, and who may access it. Those retention rules, not the export tool, should decide how long you keep the files and who can open them.

What to plan before the Chargebee contract ends

The items below are the decisions that most often get missed when a billing platform is retired. Each one depends on terms in your own Chargebee agreement and on agreements with your payment gateway and target provider, so confirm those first. Together they set the order of work for the export and the cutover.

Confirm the export window and access limits

Read your current Chargebee agreement and any order forms for how long data export and API access remain available after termination, and whether any limits apply. Do not rely on memory or on the product interface alone. Ask your account contact in writing to confirm the export window and the formats offered, so the timeline for your full export is based on a written answer.

Schedule the full export early

Plan the complete export of customers, subscriptions, invoices, credit notes and payment records well before the contract end date, not in its final week. Run one complete test export first, check row counts against the live system, and keep dated copies. A second export closer to cutover catches changes made in the meantime.

Agree the gateway token transfer

Card tokens are held by your payment gateway, not by Chargebee, so the transfer depends on that gateway and on the provider that will receive the tokens. Ask both parties in writing whether they support a token migration, what file format and secure channel they require, and how long the process takes. Start these conversations early, because they often set the critical path.

Decide which records finance must keep

Work with finance and tax teams to list the records you must retain for accounting, tax and dispute purposes: invoices, tax lines, refunds, credit notes and payment history. Confirm your retention periods with your own advisers. Store exported copies in a location your records policy covers, with a documented owner and access controls.

Plan a parallel run

Run the new billing system alongside Chargebee for at least one full billing cycle, comparing generated invoices, tax amounts and payment outcomes for the same customers. Discrepancies found here are cheaper to fix than after cutover. Decide in advance which system is authoritative for each customer during the overlap, so no account is billed twice.

Name contacts for post-exit questions

Record who at Chargebee, your gateway and your new billing provider you will contact after termination, and how to reach them. Questions about a disputed invoice, a refund or a missing record often arrive months later. Keep a named internal owner for the archive, and confirm with Chargebee how support requests are handled once the account is closed.

Questions teams ask before exporting from Chargebee

Can we export all of our Chargebee data ourselves without a consultant?

In most cases, your own team can run the export, because Chargebee lets you export entity by entity as zipped CSVs or pull the same records through its API. The harder question is whether flat files are enough for the system you are moving to. Customers, subscriptions, invoices, credit notes and payment records export cleanly, but the relationships between them, your plan and add-on structure, proration history and usage meter definitions must be rebuilt on the target platform. Start by listing which entities your account holds, confirm the current export options and retention window in Chargebee's documentation, and run a full export into a staging copy before you commit. If that test shows the mapping work is large, you can decide then whether to bring in outside help.

How long does a Chargebee export and migration take?

The duration depends on the drivers in your own account, and no fixed figure applies to every business. The main ones are the number of active subscriptions and historical invoices, how many plans, add-ons and coupons need rebuilding, how many payment gateways and accounting or CRM integrations are connected, and whether you want to run both systems in parallel through at least one full billing cycle. Data quality matters too: duplicate customers, inconsistent currencies and missing tax details add cleanup time before any import. Ask any provider for a written plan with milestones, the assumptions behind each one, and the activities the client must complete, such as sign-off on the data map and a parallel-run period. Treat any date given without those assumptions as a guess.

What do our finance, engineering and gateway contacts need to do?

Each group owns a different part of the work, and the export stalls if one of them is missing. Finance decides which balances, credit notes, deferred revenue and tax treatments must carry over, and signs off the reconciliation between Chargebee and the new ledger. Engineering runs the API pulls, builds the data mapping, deploys the target system and tests webhooks and idempotency so that no event is processed twice. Your payment gateway contact confirms whether stored credentials can be transferred, what format and timeline the gateway requires, and who authorizes the request on their side. Name one owner for each group before the project starts, and agree how cutover decisions are recorded in writing.

Can we export card numbers from Chargebee?

Do not plan on exporting full card numbers from Chargebee. Chargebee's model keeps card data with the payment gateway it connects, so your export covers billing records and references, not the card data itself. Moving stored cards is a separate process that depends on your gateway agreeing to transfer its tokens to a new processor or vault, and many gateways require a formal request and a waiting period. Where transfer is not possible, the usual fallback is asking customers to re-enter payment details through a hosted update flow, which affects revenue during the gap. Illustratively, Spreedly documents single card and encrypted batch exports to a PCI compliant receiver, which shows how vault-based exports are normally handled. Confirm the exact options with your gateway and your PCI assessor before setting a cutover date.

What does the move cost beyond the Chargebee subscription?

The cost splits into components with different payers and different timing. Chargebee fees continue until you cut over, and any overlap period adds to the total. The target platform has infrastructure costs: for Lago, servers plus PostgreSQL for application data and Redis as the job queue, and for Kill Bill, a Tomcat deployment and a supported database. Payment gateway fees apply whichever billing system you choose. Your staff time for finance reconciliation, engineering and testing is a one-time cost, while hosting, patching, upgrades and on-call support recur. External implementation is a one-time fee set by the written scope. Ask any provider to break its quote into those components, separate one-time from recurring costs, and state which items the client must provide, such as access, test environments and staff hours.

When is outside help worth paying for during a Chargebee export?

Outside help is worth considering when the risk of an error costs more than the engagement. Common triggers include a large subscription base, several gateways holding different token sets, complex proration or usage-based pricing, a requirement to run both systems in parallel, or an internal team without billing engineers who can own the target system after go-live. DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted platforms in your own cloud accounts, data centers or air-gapped networks. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and ongoing support is available as a retainer. DeployOpen does not publish a price list, and a quote follows from the written scope. DeployOpen does not issue audit reports or certifications, so ask your independent auditor what evidence it will need.

How DeployOpen scopes and delivers a Chargebee data exit

DeployOpen plans and delivers the export of billing data and card tokens out of Chargebee as a fixed-scope engagement, inside your own infrastructure. The work starts with a written scope that separates what Chargebee exports directly from what must be obtained through your payment gateway.

How we scope

Inventory every Chargebee entity you need, such as customers, subscriptions, invoices and plans, and record the export method for each.
Confirm with your payment gateway how card tokens can be exported, and which receiving party is PCI compliant.
Agree deliverables, timelines and responsibilities in writing before any export or target system work begins.

How we build

Run test exports from a Chargebee sandbox or a copy of production data and check record counts and field mappings.
Map Chargebee plans, add-ons and invoice fields to the target billing system schema, such as Lago or Kill Bill.
Test imports in a staging environment for reconciliation, including balances, credits and open invoices, before cutover.

How we hand over

Document each export step, the file formats used, and the reconciliation checks that confirmed completeness.
Deliver runbooks for the cutover order: cards and billing data, parallel running and retirement of the Chargebee account.
Hand over the self-hosted environment with configuration, backup procedures and access records in your own repositories.

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after the engagement closes.
Keep a retention plan for exported files and access logs so you can answer later audit or customer questions.
Confirm with your own compliance team which evidence the export and retention process must produce for your assessments.

How to export your data from Chargebee