Migration guide

Migrating to Kill Bill

Move your billing to Kill Bill one group of accounts at a time, on a live system. Both systems run side by side, customers keep their service, and nobody is billed twice.

Last updated: October 2026

Read the full guide
Talk to the team
Short answer

How do you migrate to Kill Bill?

Gradually. Set up a Kill Bill catalog that matches your plans, run both systems side by side, send new accounts to Kill Bill from a cut-over date, then move existing accounts in batches. Each account keeps its service, and billing in Kill Bill starts at its next billing date. Past invoices and payments stay in the old system.
Approach
Gradual, account by account, on a live system
Downtime
None planned: both systems run during the move
What moves
Accounts and their active subscriptions
What stays
Past invoices and payments, in the old system
Order
New accounts first, then existing accounts in batches
Guide
Migrating to Kill Bill, on docs.killbill.io
The approach

Move Accounts, Not the Whole System

A migration layer sends each account to the right system. A migration table records where every account stands.
Your application Sign-up, plan changes, cancellations Migration layer Routes each account to the right system Migration table account_key, migration_state Current billing system Accounts not moved yet New accounts, then migrated ones

Based on the architecture in the Kill Bill migration guide.

Five phases

Five Phases, No Big Bang

Move one group of accounts at a time, while both systems run. Each phase can be checked before the next one starts.
1

Set up Kill Bill

Build a catalog that matches your current plans, then configure invoice templates, the payment plugin, overdue rules and analytics.

The Aviate onboarding checklist: catalog configured, invoice template configured, customer account created, create a subscription, see your first invoice, and a button to choose a deployment method
With Aviate, an onboarding checklist covers the catalog, the invoice template and the first account.
DockerKubernetesTomcatPostgreSQLMySQLMariaDB
2

Run both systems

Send new-account requests to both systems, compare the results and explain every difference.

3

Switch new accounts

From a cut-over date, new accounts go only to Kill Bill. Existing accounts stay on the old system for now.

Key date: one cut-over date for all new accounts
Cut-over date for new accounts New accounts go to Current billing system New accounts go to Each dot is a new customer. Existing accounts stay where they are for now.
4

Migrate existing accounts

Move accounts in batches, each on its own date, chosen close to its next billing date.

Key date: one cut-over date per account
The accounts list in Kaui with account IDs, external keys, currency, time zone, locale and balance
Migrated accounts in Kaui, each with its external key.
5

Retire the old system

Once every account has moved or closed, keep the old system for reference, then switch it off.

The account timeline in Kaui, with each invoice, its amount, balance, invoice number, bundle and the event that created it
The account timeline in Kaui: check the first invoices after the move.
Scope

What Moves and What Stays

Migrate the current state, not the history. Functional changes come later, once Kill Bill runs your billing.

Moves to Kill Bill

  • ✓Accounts, with the old account ID kept in a custom field
  • ✓Active subscriptions, in their current state
  • ✓The original subscription start date, for support
  • ✓Pending plan changes and cancellations, replayed through the API

Stays in the old system

  • –Past invoices and payments: they cannot be replayed
  • –Cancelled subscriptions
  • –Past upgrades and downgrades
  • –Accounts with an unpaid balance, until they pay or are written off
A Kill Bill account in Kaui with its ID, external key, currency, balance, bill cycle day and next invoice date, and a Custom Fields tab
A migrated account in Kaui. The old account ID can be kept in a custom field.
Dates

No Gap in Service, No Double Billing

A moved subscription keeps its original start date for the service. Kill Bill starts billing at the next billing date, so nothing is charged twice.
Already paid in the current system Billed by Kill Bill Service continues, no interruption 1. Original start date The service keeps this date 3. Next billing date Kill Bill sends its first invoice 2. Cut-over date The account moves, just before

Illustration. The next billing date is the date the current system has already charged up to.

A subscription bundle in Kaui with the plan, phase, start date and charged up to date
In Kaui, each subscription shows its start date and the date it is charged up to.
In the API

Two Calls That Do Most of the Work

Accounts and subscriptions are recreated through the Kill Bill API. No direct database writes.
# 1. Keep the old account ID on the Kill Bill account
POST /1.0/kb/accounts/{accountId}/customFields
[ { "name": "legacy_account_id", "value": "ACC-10231" } ]
# 2. Recreate the subscription: service from the original
#    start date, billing from the next billing date
POST /1.0/kb/subscriptions
     ?entitlementDate=2024-03-14
     &billingDate=2026-11-01
{ "accountId": "{accountId}", "planName": "starter-monthly" }

Request bodies shortened. Full parameters are in the API reference.

Per account

Six Steps, Safe to Resume

A migration table tracks each account through the same states. Each step can run again if it fails, so a batch can resume where it stopped.
Migration entry createdINIT
Account copiedACCOUNT_MIGRATED
Invoicing pausedAUTO_INVOICING_OFF
Subscriptions recreatedSUBSCRIPTIONS_MIGRATED
Old system stops billingOLD_SUBSCRIPTIONS_CANCELLED
Invoicing resumedMIGRATED
account_keymigration_statecut_over_datelast_error_msg
ACC-10231MIGRATED2026-11-01·
ACC-10232OLD_SUBSCRIPTIONS_CANCELLED2026-11-01·
ACC-10233SUBSCRIPTIONS_MIGRATED2026-11-08·
ACC-10234ACCOUNT_MIGRATED2026-11-08Timeout, retry
ACC-10235INIT2026-11-15·

Illustration, with the columns the migration guide suggests. A failed step is retried from the state the account reached.

Integrations

Keep Your Gateway and Tax Engine

Kill Bill talks to payment gateways and tax engines through plugins. Start with the plugin for the provider you use today, or write your own.
Payment gateways
Tax engines
Runs on
The Aviate plugin marketplace with the Aviate, Braintree, Hyperswitch and Stripe plugins
Payment and tax plugins, installed from the Aviate plugin marketplace.
Choosing a deployment method in Aviate: an AWS single AMI with Kill Bill, Kaui and the database, or a local Docker Compose setup
Run Kill Bill on AWS or locally with Docker Compose.
Kill Bill or Aviate

Migrate With the Open Source, or With the Team

Both run the same engine. Aviate adds tools and direct access to the engineers who build it.

With Kill Bill open source

  • ✓The migration guide on docs.killbill.io
  • ✓The REST API and client libraries
  • ✓Kaui to check accounts, subscriptions and invoices
  • ✓Community help on the mailing list, no SLA

With Aviate

  • ✓Everything in Kill Bill open source
  • ✓An onboarding checklist and a catalog editor
  • ✓Health to watch queues and failed events during batches
  • ✓Level 3 support from the engineers, on a dedicated Slack channel
Watch out

Five Things to Plan For

Cancelling old subscriptions is the riskiest stepRollback becomes difficult after it, and cancellation in production can only happen once. Do it just before the next billing date.
Invoices will not match line for lineKill Bill bills on events while many older systems run batches, so timing and proration can differ.
Do not move accounts with a balanceLet unpaid accounts go through dunning first: they pay and move, or are written off.
Avoid editing the database directlyUse the APIs. Direct database changes are a last resort.
Order add-ons and multi-phase plans carefullyBase plans before add-ons, and decide how trial or discount phases are recreated.
FAQs

Frequently Asked Questions

Can we migrate to Kill Bill without downtime?
Yes. The recommended approach runs both systems side by side: new accounts move first, then existing accounts move in batches, each on its own date. Customers keep their service throughout.
What data moves to Kill Bill?
Accounts and their active subscriptions, in their current state, with the original start date kept for support. Pending plan changes and cancellations are replayed through the API.
Do past invoices and payments move?
No. Kill Bill cannot replay past invoices and payments. Keep the old system available for a few months, or combine old and new data in your reports or APIs.
How do we avoid billing customers twice?
Pause invoicing on the account during the move, recreate subscriptions with billing starting at the next billing date, then cancel the old subscriptions. Entitlement keeps the original start date, so the service does not stop.
Which accounts should move first?
New accounts first, from a cut-over date. Then existing accounts with no unpaid balance, in batches, each on a date close to its next billing date.
How long does a migration take?
It depends on your catalog and integrations. In the approach described in the guide, most accounts move within about a week, and the old system stays available for a few months.
Can we migrate from a home-grown billing system?
Yes. The approach is the same whatever the old system: map your plans to a Kill Bill catalog, run both systems side by side, then move accounts in batches.
Who can help with a migration?
The migration guide on docs.killbill.io covers the approach in detail. Kill Bill partners run implementation projects, and Aviate includes Level 3 support from the engineers who build and maintain the platform.
Kill Bill logo

Planning a migration?

Read the full migration guide, or talk to the team about your catalog, your integrations and your timeline. A technical member of the team will reply.
Talk to the team
Read the full guide