How to export your data from Zuora

How to export your data from Zuora before the contract ends

Billing data leaves Zuora through documented data source exports, one object at a time, and some items need a separate path. If a renewal, a pricing change or a data residency requirement has you planning an exit from Zuora Billing, that split is the first thing to understand. Accounts, subscriptions, invoices and payment records form the core of a billing history, and each has to be requested and checked as its own export. Anything outside those objects, such as stored payment credentials or reports built on older exports, needs its own route. Before you plan the work, confirm with Zuora which objects, file formats and download windows apply to your tenant and contract, because export options and retention terms can change.

Stored card data is the item teams most often misjudge. Card numbers are usually held by the payment gateway or a vault, outside the billing record, so an invoice export will not carry them. Ask your payment provider and Zuora how existing payment methods can be transferred, and whether the receiving provider accepts tokens or needs a PCI DSS-compliant export. Confirm with your assessor which party owns that step. Also list every report, scheduled export and integration that feeds finance or the general ledger, because an older export you depend on may no longer be offered. Use that list as the input to your scope before any export runs.

The export is only the first step of the migration. Once files are in hand, map each object to its target in Kill Bill or Lago, since the two models represent plans, add-ons and usage differently. Kill Bill, for example, is a Java server driven through REST APIs and plugins, so imports run through those APIs and need engineers who can script and reconcile them. Keep a checksummed copy of every extract in storage you control, with access logs and a retention rule, and agree with finance which totals each export must match before cutover. Confirm in writing the terms for additional exports and the access period after termination, because those dates set how much time you have.

Which Zuora objects you can export and in what format

This table lists the Zuora billing objects a destination system needs, the export method and file format to check for each, and the limits to confirm. Treat it as a checklist and verify every method, format and window against Zuora's current data source export documentation and a test export before the contract ends.

Zuora object	Export method to confirm	File format to confirm	Limits to confirm
Accounts	Data source export of the account object	Generated file, format and encoding to confirm	Field list, record limits and whether bill-to and sold-to contacts export with it
Contacts	Data source export of contact records	Generated file, format to confirm	Whether contacts link to accounts by key, and how to re-link them
Subscriptions and rate plans	Data source export of subscription and rate plan charge objects	Generated file, format to confirm	Whether amendment history and charge segments export, or only current versions
Invoices and invoice items	Data source export of invoice and invoice item objects	Generated file, format to confirm	Whether posted and draft invoices differ, and whether PDFs need a separate export
Payments	Data source export of payment objects; gateway tokens handled separately	Generated file, format to confirm	Card data is not a plain export; confirm token transfer with the gateway
Credit and refund records	Data source export of credit balance and refund objects	Generated file, format to confirm	Whether applied and unapplied credits export with their invoice links
Usage uploads	Data source export of usage records, plus retained original upload files	Generated file, format to confirm	Whether original uploaded files stay available and for how long
Product catalog	Data source export of product, product rate plan and charge objects	Generated file, format to confirm	Whether catalog history, discounts and tiered pricing export completely
Generated file download window	Download from Zuora's export listing before files expire	Not applicable	Exact window length and which legacy export types have been retired; confirm in writing

How the export files and download window work in practice

Treat every Zuora export file as a deliverable the moment it is produced, because the download window is limited and the file may not be there when you come back for it. Before you plan any extract, confirm with Zuora the exact length of the download window, how long files are retained, which file formats each data source export supports and whether large objects are split into multiple files. Once the job completes, a named person should download each file, record it and move it into your own storage on the same day. Re-running a job later is not a reliable backup plan, since the source records may have changed in the meantime and the second extract will not match the first.

Name each file so that its origin and position are obvious without opening it. A practical convention includes the data source or object name, the job identifier, the extract date and time, and a part number for split files, for example invoice_part002_of_010.csv (illustrative). Record the expected number of parts from the job output or the Zuora UI so that a missing part is visible immediately. Then check row counts for each file against the record count shown in the Zuora UI or in a standard report covering the same object and date range. A mismatch is a reason to stop and investigate before anything is loaded into a new system, and it is far easier to resolve while the source job and its files are still available.

Compute a checksum, such as SHA-256, for each file as soon as it is downloaded, and store the file, its checksum and its row count together in a manifest in your own object storage or file store. Restrict write access to the migration team, enable versioning or immutability controls if your storage supports them, and apply a retention period agreed with finance and legal. Re-verify checksums before each import step so that you can show a file has not changed since it left Zuora. Assign one owner for retrieval, one reviewer for row counts and one approver for sign-off, and document what happens if a window closes before a file is retrieved, so the decision is made in advance rather than under deadline pressure.

What cannot be exported as plain data and how teams work around it

Some Zuora billing history never arrives as a clean CSV. Card credentials, legacy exports, calculated amounts and configuration each need a different plan before the contract ends. Treat each category as a separate line item in the migration plan.

Stored card and bank credentials

Card numbers and bank account tokens sit with the payment gateway Zuora connects to, not as readable fields in Zuora. Any export is a token or a reference, and the receiving processor usually cannot use it directly. Plan to re-collect payment methods through the new processor, sending customers a secure update link. Ask your gateway in writing whether it supports a PCI-compliant token migration, and what that process requires from you.

Legacy exports Zuora no longer provides

Some older export formats and data source objects may be retired or limited for newer tenants, so a script that worked for a prior migration may fail. Records that exist only in a retired export cannot be recreated from current tooling. Ask Zuora in writing which legacy exports remain available for your tenant, and get the answer before the contract end date is set. Keep the written reply with the migration plan.

Calculated proration and tax outputs

Zuora calculates proration amounts, tax lines and rounding at invoice time, and those results are not always stored as standalone fields in an export. Recalculating them in Kill Bill or Lago with different rules will produce different totals for the same usage. Export the finalized invoice lines and tax breakdown as recorded, then document each calculation rule so the destination reproduces past results or records the difference.

Workflows and custom notifications

Approval workflows, dunning rules, custom email templates and event triggers are configuration rather than customer data, so they do not appear in an object export. Their logic must be rebuilt in the destination, usually as plugins, webhooks or scheduled jobs. Inventory every active workflow and notification in Zuora, screenshot or document each one, and assign an owner to rebuild and test it.

Archived invoices and reports

Invoice PDFs, statements and historical reports rendered by Zuora are generated output, and they may not be regenerable from raw data after the contract ends. For audit and customer disputes, keep an archive of rendered PDFs and standard reports in your own storage, indexed by account and invoice number. Confirm retention obligations with your finance and legal teams before deciding how long to keep them.

Why payment credentials need their own exit plan

Card and bank tokens are usually tied to the payment gateway that holds them, so the token is often the hardest part of leaving Zuora. A billing engine such as Kill Bill or Lago calculates what to charge and when, but it does not carry stored card numbers with it. Moving subscriptions to a new system can therefore mean one of two things: asking the current gateway for a token migration to a receiving provider, or re-collecting customer consent and payment details through a new flow. Each path has different lead times, customer communication needs and failed-payment risk, so the choice belongs in the cutover plan, not after the contract ends.

A token export path depends on the gateway that holds the tokens and on the provider that will receive them. Some gateways export vaulted payment methods to a PCI compliant third party, sometimes as a single card export or an encrypted batch file, and the processing window and fees are set by the gateway, not by Zuora. Confirm with the gateway whether it supports export at all, which receiving services it accepts, how long a batch takes, and whether network tokens or account updater services carry over. Also confirm whether Zuora itself stores any card data or only references to gateway tokens, because that determines what Zuora can hand over.

PCI DSS obligations apply to any system that stores, processes or transmits card data, including a self-hosted billing engine and any middleware that moves files between systems. Plan for the scope of that environment before any card data touches it, and ask your assessor or qualified security assessor how a token migration changes your scope. Treat the token and card-data export as its own workstream with a named owner, a written sign-off from the gateway, and a test batch before the cutover date. Ask both Zuora and the gateway to confirm token portability in writing, and record the answer in the migration plan.

Choosing where exported data lands: Kill Bill or Lago

Kill Bill is a standalone Java server, packaged as a WAR file and typically run in Tomcat. Applications call it through REST APIs, plugins for payment gateways, tax and fraud providers are deployed as JARs alongside it, and it is event-driven and multi-tenant. For a Zuora export, this means your extracted accounts, subscriptions, invoices and payment records must be shaped to fit Kill Bill's account, bundle, subscription and invoice model, and loaded through its APIs rather than dropped into a database.

Catalog mapping: Zuora product rate plans and charges need a matching Kill Bill catalog, so export product and charge definitions along with subscriptions.
Account and invoice history: Keep account identifiers and historical invoice numbers in a crosswalk so credits, adjustments and balances can be reconciled after import.
Database and runtime: The core team tests against MySQL, MariaDB 10 and PostgreSQL 12, and the Tomcat install guide requires JDK 11, so plan staging with the same stack.
Multi-tenancy: Decide which tenant each Zuora entity maps to before loading anything.
Payment references: Export gateway tokens or processor references separately, because Kill Bill plugins must reconnect to them.

Confirm the current import approach and API calls in the Kill Bill getting started guide before you write any extract specification.

The export sequence and verification steps in order

This sequence turns Zuora's data into a set of archived files that have been counted, reconciled and signed off against the source. Each step ends with a check that either clears the next step or sends the work back, so the final manifest can stand as your record of what left Zuora.

Inventory objects and open invoices
Billing operations lists every Zuora object in scope, including accounts, contacts, subscriptions, products and rate plans, invoices, payments, credit memos, refunds and usage, and records which ones hold open balances or unpaid invoices. Confirm the list against your contract, your current Zuora data source exports and any custom objects your team relies on. The step is done when the finance lead has signed off the inventory and the open-invoice list, which becomes the baseline for every later check.
Freeze the product catalog
Product management stops changes to products, charges, rate plans and pricing in Zuora for the export window, and records the catalog version in writing. A frozen catalog means the exported subscriptions and invoices can be mapped to one fixed set of prices. Confirm with the product owner that no pending amendments are queued, and file the catalog snapshot with the inventory. The step is complete when the product owner and billing lead have both signed the freeze record.
Run exports object by object
The data engineer runs the Zuora data source exports one object at a time, using the file format and date range that the inventory specified, and logs the job name, object, time and requester for each run. Keep account and invoice exports in the same cut-off window so balances reconcile. Check that each export job completes without errors before starting the next one. The step is done when every object on the inventory has a completed job in the log.
Retrieve and archive each file
Download each exported file inside the download window Zuora provides, and do not rely on re-running an export later. Store the original files in write-once or access-controlled storage in your own environment, and record a checksum for each file in the log. Confirm that the checksum on the archived copy matches the one recorded at download. The step is complete when every file is archived, checksummed and listed in the log, and the security owner has confirmed the storage location and access rules.
Verify row counts and totals
The data engineer compares row counts and summed amounts in each file against the matching Zuora reports for the same cut-off date, such as invoice totals by period and account counts by status. Any difference must be explained and resolved, or the export re-run with the same parameters. Finance signs off on totals and the data engineer signs off on counts. The step is done when every object shows a matched count and total, or a written explanation approved by finance.
Reconcile open balances and tax
Finance compares open balances, credit memos, unapplied payments and tax amounts in the exported files with Zuora's balance and tax reports. Confirm which tax rules and jurisdictions applied to each invoice, because the target billing system will need them to reproduce history. Record every mismatch and its resolution. The step is complete when the tax lead and finance lead have signed the reconciliation, and every open balance is either carried over with its amount or closed in Zuora before the cut-off.
Record card and token status with each gateway
The payments lead lists every payment method linked to an active account and records, for each one, which gateway holds it, whether it is active, expired or pending, and whether the gateway allows the token to be exported or re-vaulted. Confirm these details with each gateway's own documentation or support team, since Zuora exports do not carry card data. The step is done when each payment method has a recorded status and an owner for the decision on whether to re-collect or migrate it.
Keep a signed-off manifest
The billing lead compiles a manifest that lists each file, its checksum, the row counts, totals, catalog version, reconciliation outcome and gateway status, and sends it for signature to the finance lead, the data engineer, the payments lead and the security owner. Store the manifest alongside the archived files, and treat it as the reference point for the migration. The step is complete when all four signatures are on the manifest and it is stored with the archive.

What to plan before the Zuora contract ends

The notice period is when export rights, deadlines and data scope get settled, and they are hard to renegotiate once the contract lapses. The cards below cover what to confirm in writing, when to freeze changes, and how to budget the mapping and validation work that follows the extract.

Confirm export entitlements and deadlines

Read the contract for the export rights you are entitled to, the number of extracts included, and any time limit on downloads. Ask Zuora or your implementation partner to confirm in writing how long each export file stays available after it is generated, and whether a re-run is charged. Record who at your company owns the download window, since a missed window can mean requesting the data again. Cost drivers here are data volume and the number of extract runs you need.

Get legacy exports in writing

Older export jobs and data sources may have been retired or changed over the years. Ask for a written list of which legacy exports remain available, which have been removed, and what replaces each one. Compare that list against the objects your billing reports, finance team and integrations depend on. Any gap found now is cheaper to solve with a workaround than after the subscription ends.

Agree a catalog and invoice freeze date

Set a cut-off date after which no product, price, subscription amendment or invoice adjustment is made in Zuora unless it is also recorded in the migration file. Without a freeze, the extract and the target system drift apart during the migration. Ask the vendor to confirm in writing whether bulk changes or backdated corrections are allowed after that date, and who approves exceptions.

Plan parallel runs

Plan at least one billing cycle where Zuora and the target system both calculate invoices from the same inputs, and compare the outputs line by line. This shows whether rating, tax, proration and credits match before Zuora stops producing invoices. Agree with finance which discrepancies block cutover. Parallel runs add engineering and finance time, so ask your partner to include them explicitly in the written scope.

Budget for mapping and validation

Mapping Zuora objects to the target data model, and validating the imported records, usually takes more effort than the extract itself. Budget for catalog translation, reconciliation of open balances, and checks on payment method references. Ask a partner for a fixed-scope estimate that lists the objects in scope, the validation rules and the people who sign off. Cost drivers are data volume, catalog complexity and the number of integrations that read or write billing data.

Confirm payment token handling

Card tokens and payment method references usually cannot be copied out of Zuora in a usable form, because they belong to the payment gateway. Ask your gateway and Zuora, in writing, what export or re-tokenization path exists and how long it takes. Plan the gateway connection in the target system during the notice period so that recurring payments do not stop at cutover.

Common questions about exporting data from Zuora

How long does a full data export from Zuora take?

The research behind this page does not give a duration for a Zuora export, so confirm the timing with Zuora and with your own data. The effort is driven by the number of accounts, the years of invoice and payment history you keep, how many data source exports you need, and whether you extract by object or by date range. Usage records and attachments add volume. Ask your Zuora administrator to size each object before you plan. A dry run on a partial extract, checked against control totals, shows the real effort faster than any estimate. Plan the dry run before the final extract so that any surprises surface while Zuora is still your system of record.

Can our own team export everything from Zuora without a partner?

Many teams can run the extracts themselves if they hold the right Zuora permissions and have someone who knows the billing data model. The harder work is usually after the files arrive: mapping objects to a target schema, checking that totals reconcile to the general ledger, and documenting what was moved and what was left behind. Teams that lack this experience tend to find gaps during cutover. Decide early which parts your staff will own and which need an outside reviewer. Confirm your administrator's access, export permissions and file handling rules with Zuora first, because those settle whether an in-house export is practical at all.

What do finance and engineering each need to provide for a Zuora export?

The export needs both teams, and the split is clearer when written down:

Finance defines the source of truth for balances, open invoices, credit memos, tax treatment and revenue periods, and signs off the reconciliation totals.
Engineering handles access to Zuora, the target data model, scripts or tools for extraction, encrypted storage of the files, and access controls on every copy.
Both agree a change freeze window so that billing runs do not alter the data mid-extract, and a named owner for each object.

Without finance sign-off on totals, engineering can produce complete files that are still wrong.

How long is the download window for Zuora data exports, and where do I confirm it?

The research behind this page does not confirm the download window, so check Zuora's current documentation for data source export availability and retention before you plan. Treat the window as a hard deadline. Record the moment each export completes, calendar the expiry, and download and checksum every file as soon as it is ready. Keep a second copy in your own encrypted storage. If a file expires, request a new export and build that delay into your plan. Ask your Zuora account contact to confirm the window in writing for your contract and tenant.

Can card numbers be moved out of Zuora?

Card data is often held by the payment gateway or vault that tokenizes it rather than by the billing platform, so first confirm where your card data actually sits and who holds the tokens. Export depends on the gateway's contract and on whether the receiving provider is PCI DSS compliant. As an illustration of what to ask, Spreedly documents exporting vaulted payment methods to a PCI compliant third party through a single card export or an encrypted batch file, generally processed within 2 weeks, with one free export per merchant per receiving service. Your own gateway and receiving provider will have their own terms, so confirm them in writing before you plan.

What does a fixed-scope exit engagement from DeployOpen cover?

DeployOpen works on fixed scope. The scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that written scope. DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, so an exit engagement typically covers planning the extract, setting up the receiving environment, validating the data against control totals and documenting the evidence. DeployOpen prepares systems and records for compliance assessments but does not issue audit reports or certifications. Ask for the deliverables and exclusions in the written scope, including who confirms Zuora's limits and export terms.

What should a Zuora exit checklist include before the contract ends?

Confirm the following objects are in your extract plan, then check each one against control totals:

Accounts, contacts and bill-to and sold-to details
Subscriptions, amendments and their effective dates
Product catalog, rate plans and charge definitions
Invoices, credit memos, payments and open balances
Usage records and the rating inputs behind them
Tax configuration and tax history
Attachments, notes and audit history your auditors may ask for

Record which objects you export, which you rebuild, and which you retire, with the owner and sign-off for each.

How DeployOpen scopes and delivers a Zuora data exit

DeployOpen approaches a Zuora data exit as a written, fixed-scope engagement inside your own infrastructure. We agree which objects, files and reconciliation checks are in scope before extraction starts, then build, test, document and hand over the export pipeline so your team can keep the records.

How we scope

Inventory the Zuora data sources you use and confirm which objects must leave before the contract ends.
Agree the target destination, file formats and storage location inside your own cloud or data center.
Record the written scope, deliverables and timeline with you before any export work begins.

How we build

Script and schedule exports within the seven-day download window, keeping each run logged and repeatable.
Reconcile record counts and control totals against the Zuora source for accounts, subscriptions and invoices.
Test restore and load steps in a non-production environment so the exported data stays usable outside Zuora.

How we hand over

Deliver the export scripts, data dictionary, reconciliation reports and an extraction runbook to your team.
Document which legacy exports are no longer available and what alternative evidence we captured instead.
Walk your finance and engineering staff through the checklist so ownership of the archive is clear.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
Retainer support can cover re-running reconciliations if a late Zuora correction changes source records.
Ask for the support terms, response expectations and ownership of the archive in your written quote.

How to export your data from Zuora