anchor.diff:  
   Other state such as non active subscriptions, past invoices, and payments *don't need* to be migrated into Kill Bill to have the system function correctly, but **that data may still need to be available in some fashion**. By not migrating that data into Kill Bill, this simplifies the problem:
   
  -* **Non active subscriptions**: Migrating those means migrating more data; also it is often the case that the older the data the less 'clean' it is and the harder it is to migrate (associated `Plan` may not be active anymore, previous bugs from existing billing systems may create data that is difficult to migrate, ...). Also, while this is feasible, this does not add too much value unless one wants to also migrate past invoices.
  -* **Past Invoices**: Those are difficult to migrate as such, because they can't simply be replayed by Kill Bill (if we were to migrate all subscriptions with their historical state and let Kill Bill catch up with invoices, the result would be a set of invoices not exactly identical to the original system (pro-ration logic would be different, catalog may have been configured slightly differently on old system and in Kill Bill,...) and so those would not be useful as they could not provide a real replacement for past invoices. Another strategy would be to insert them manually in the Kill Bill invoice table to make sure they exactly match, but then invoices and subscriptions would not correspond exactly and system would try to correct the state. Also such a route would require inserting data directly or providing custom endpoints to touch these tables, both of which are risky and error prone initiatives.
  -* **Past Payments**: The same set of issues we described for invoices apply to payments. They need to match exactly past invoices and the same set of challenge exists here.
  +* **Non active subscriptions**: Migrating those means migrating more data; also it is often the case that the older the data, the less 'clean' it is and the harder it is to migrate (associated `Plans` may not be active anymore, previous bugs from existing billing systems may create data that is difficult to migrate, ...). Also, while this is feasible, this does not add too much value unless one wants to also migrate past invoices.
  +* **Past Invoices**: Those are difficult to migrate as such, because they can't simply be replayed by Kill Bill (if we were to migrate all subscriptions with their historical state and let Kill Bill catch up with invoices, the result would be a set of invoices not exactly identical to the original system (pro-ration logic would be different, catalog may have been configured slightly differently in the old system and in Kill Bill, ...) and so those would not be useful as they could not provide a real replacement for past invoices. Another strategy would be to insert them manually in the Kill Bill invoice table to make sure they exactly match, but then invoices and subscriptions would not correspond exactly and the system would try to correct the state. Also, such a route would require inserting data directly or providing custom endpoints to touch these tables, both of which are risky and error prone initiatives.
  +* **Past Payments**: The same set of issues described for invoices apply to payments. They need to match exactly past invoices and the same set of challenges exists here.
   
   We identified the minimal state that neeeded to be migrated and also explored why migrating more is a difficult endeavor. So, the next question is whether this is a realistic strategy. One way to answer is to look at the use cases for this data (that we don't plan to migrate directly into Kill Bill), and the way we can make that info available in some fashion:
   
  -* **Customer Use Case**: Customers may still need to access their old invoices and payments. Assuming this data is static one could keep those (past invoices and payments) outside of the pure Kill Bill tables (that could still be in the same database with additional tables, or using an entirely different database) and **provide new apis that would fetch existing invoices and payments by merging old data with the new one from Kill Bill**.
  -However, keeping that data completely static is a challenge because customers may still require some invoice adjustements, payment refunds associated with this old data... So, a good strategy here is to keep the old billing system alive for a while after the migration has been completed and serve those invoices/payments from the old system, allowing customer service to still make the changes through the old system. After a while (maybe a few months) there will be very few such adjustments to make on those old invoices/payments and that data can be fetched and served from a static source. Isolated cases where customers still require some changes associated with these old invoices/payments cannot be made anymore but customer could still be satisfied by generating invoice or payment credit. At this point Accounting/Finance departments would be impacted minimally because the number of such requests becomes very few. So finally the old system can be fully unplugged.
  -
  -* **Finance/Acounting departement**: They will still require old invoice and payment data to run reports but it does not necessarily need to be part of Kill Bill. A good alternative is to provide some kind of a view that will merge both the old data (from old billing system) and the new data coming from Kill Bill. The old data could be ETLed from old billing system as long as it is alive and then data could be materialized after it has been extinct.
  +* **Customer Use Case**: Customers may still need to access their old invoices and payments. Assuming this data is static, one could keep those (past invoices and payments) outside of the pure Kill Bill tables (that could still be in the same database with additional tables, or using an entirely different database) and **provide new apis that would fetch existing invoices and payments by merging old data with the new one from Kill Bill**.
  +However, keeping that data completely static is a challenge because customers may still require some invoice adjustements, payment refunds associated with this old data, ... So, a good strategy here is to keep the old billing system alive for a while after the migration has been completed and serve those invoices/payments from the old system, allowing customer service to still make the changes through the old system. After a while (maybe a few months), there will be very few such adjustments to make on those old invoices/payments and that data can be fetched and served from a static source. Isolated cases where customers still require some changes associated with these old invoices/payments cannot be made anymore but customer could still be satisfied by generating invoice or payment credit. At this point Accounting/Finance departments would be impacted minimally because the number of such requests becomes very small. So finally the old system can be fully unplugged.
  +
  +* **Finance/Acounting departement**: These teams will still require old invoice and payment data to run reports but it does not necessarily need to be part of Kill Bill. A good alternative is to provide some kind of view that will merge both the old data (from the old billing system) and the new data coming from Kill Bill. The old data could be ETL'ed from the old billing system as long as it is alive and then that data could be frozen after it has been turned off.
   
   ==== Clean Accounts
   
  -A corollary of what we described earlier is that we should only migrate clean accounts, i.e accounts that have a $0 balance. Any other account would have unpaid invoices, and since we don't plan to migrate invoices, that balance is hard to carry over in a clean form.
  -
  -A good and easy strategy here is to do the migratiuon is several batches making sure we reach a point of convergence:
  -
  -1. A first migration batch with all clean accounts (hopefullly this accounts for the bulk of them)
  -2. The current dunning strategy should be in place to first email customers, and moving through a gradual degrade of the service up to the point where subscriptions either become paid (and then account can be migrated) or subscriptions become cancelled (invoices are written off), and there is nothing to migrate for that account. This means unplugging the system will not happen overnight, this will be a gradual process (typicall most accounts are migrated within a week, and then syystem stays up for a few more months).
  -3. The point of convergence is evenutally reached because:
  +A corollary of what we described earlier is that we should only migrate clean accounts, i.e accounts that have a $0 balance. Any other account would have unpaid invoices, and since we don't plan on migrating invoices, that balance is hard to carry over in a clean form.
  +
  +A good and easy strategy here is to do the migration is several batches making sure we reach a point of convergence:
  +
  +1. A first migration batch with all clean accounts (hopefully, the bulk of them)
  +2. The current dunning strategy should be in place to first email customers, and moving through a gradual degrade of the service up to the point where subscriptions either become paid (and then accounts can be migrated) or subscriptions become cancelled (invoices are written off), and there is nothing to migrate for that account. This means unplugging the system will not happen overnight, this will be a gradual process (typicall most accounts are migrated within a week, and then the system stays up for a few more months).
  +3. The point of convergence is eventually reached because:
     ** existing customers who have unpaid invoices either pay and get migrated or don't pay and 'die' in the old system
  -  ** new customers are already on the new system and so they will not impact the final date at which old system could be unplugged (more on that later)
  -
  -
  -
  -=== How Does Migration Work?
  +  ** new customers are already on the new system and so they will not impact the final date at which the old system could be unplugged (more on that later)
  +
  +
  +=== How Does The Migration Work?
   
   ==== Migration Cutover Dates
   
   The first thing to discuss is the **cutOverDate**, that is the date at which Kill Bill starts handling requests. In fact, we made the assumption that the migration would happen on a live system (with no downtime), and that has two consequences:
   
   * The first consequence is that there needs to be a point in time where **new accounts** will be created in Bill Bill. While this is not a migration data issue (because those new accounts would never see the old system, so there is no data to migrate per say), we still need to define when is that **newAccountCutOverDate**
  -* The second consequence is that because we will make that migration work with no downtime, it does not need to happen all at once. In fact we propose to migrate the existing accounts on a per account basis. That way each account is migrated independently of the other (and occasional failures can be investigated and retried). So, we will have one **cutOverDate** per account.
  -
  -So assuming we have N existing accounts to migrate, we end up one **newAccountCutOverDate** and N **cutOverDate**. We need to first move new accounts to Kill Bill before migrating any of the  existing accounts (i.e. `newAccountCutOverDate` < `cutOverDate{i, i E [1, N]}` because:
  -
  -* Only when old billing system stops accepting new accounts, can we compute how many existing accounts there are (N becomes fixed at this point),
  -* This also allows to verify that Kill Bill works as expected before we start migrating data.
  +* The second consequence is that because we will make that migration work with no downtime, it does not need to happen all at once. In fact, we propose to migrate the existing accounts on a per account basis. That way, each account is migrated independently (and occasional failures can be investigated and retried). So, we will have one **cutOverDate** per account.
  +
  +So, assuming we have N existing accounts to migrate, we end up with one **newAccountCutOverDate** and N **cutOverDate**. We first need to move new accounts to Kill Bill before migrating any of the  existing accounts (i.e. `newAccountCutOverDate` < `cutOverDate{i, i E [1, N]}` because:
  +
  +* Only when the old billing system stops accepting new accounts can we compute how many existing accounts there are (N becomes fixed at this point),
  +* This also allows us to verify that Kill Bill works as expected before we start migrating existing data.
   
   ==== Migration Framework
   
  -The migration code consists in several pieces:
  -
  -* Ability to make api calls to old billing system (may already exist in some form)
  -* Ability to make api calls to Kill Bill (mandatory to handle new accounts regardless of migration data)
  -* Ability to route traffic to one (or both system)
  +The migration code consists of several pieces:
  +
  +* Ability to make api calls to the old billing system (may already exist in some form)
  +* Ability to make api calls to Kill Bill (mandatory to handle new accounts, regardless of migration data)
  +* Ability to route traffic to one (or both systems)
   * Provide migration apis:
   ** Ability to set/get **newAccountCutOverDate** 
   ** Ability to migrate specific accounts (would set things like **cutOverDate** for that account)
   
  -
  -The choice of where those pieces are implemented really depends on the current architecture of the system. For instance if the code interracting with the existing billing system is well isolated, those new functions could take place at this level (client side). Conversely, if there are many components already interracting with the existing billing system, it might make sense to provide a new proxy server that encapsulate all that logic and have those components go through that proxy (and from an implementation point of view that proxy server could live in the same webapp as Kill Bill and access some new tables in the same database). 
  -
  -The figure below shows that the migration logic owns its own migration state. It is also able to make api calls to both old billing system and Kill Bill and provide an interface to the existing Billing&Payment Components (systems that currently interact with the old billing system). From a logical point of view, the migration logic has been shown in a seprate box, but again this could be implemented in various ways.
  +The choice of where those pieces are implemented really depends on the current architecture of the system. For instance, if the code interacting with the existing billing system is well isolated, those new functions could take place at this level (client side). Conversely, if there are many components already interacting with the existing billing system, it might make sense to provide a new proxy server that encapsulates all of that logic and have those components go through that proxy (and from an implementation point of view, that proxy server could live in the same webapp as Kill Bill and access some new tables in the same database). 
  +
  +The figure below shows that the migration logic owns its own migration state. It is also able to make api calls to both the old billing system and Kill Bill and provide an interface to the existing Billing&Payment Components (systems that currently interact with the old billing system). From a logical point of view, the migration logic has been shown in a seprate box, but again, this could be implemented in various ways.
   
   image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/migration/migration_logic.png[align=center]
   
  
positive.code: == Overview
  
  This guide is intended to provide some guidelines for running migrations from an **existing billing system** to **Kill Bill**.
  It is by no mean an exact recipe book to follow, but it provides some recommendations on how to do things (based on previous experiences) and highlight some specific areas of concern. The assumption is that there is already an internal or third party billing system in place, and so the goal of the migration is to preserve the current state of the system and yet reach a point when this old system can be fully unplugged. The old billing system currently:
  
  * receives some live traffic, and migration should not cause any downtime
  * contains existing state (subscriptions, invoices, ...) that need to be migrated without impacting customers
  * offers apis that are used by one or several systems within the company
  * provides a UI for customer service (CS) use to handle customer tickets and that functionality still need to exist in some form
  * provides state/data that is used by accounting/financial departments and this data will need to remain available for these departments
  
  The end goal of the migration is to make sure that we can **unplug completely the old billing system** and yet provide the same level of service (or better) for the customers and the various departments in the organization.
  
negative.code: 
  ==== Catalog Mapping
  
  We discussed in the Pre-Requisites section, the importance to build a Kill Bill catalog that will provide the same kind of products/plans than the one configured in the old billing system. In addition to the Kill Bill catalog, we also need a **mapping layer** between the name of the plans defined in the old system and the name of the `Plan` in the Kill Bill catalog. At the time of the migration, the plan associated with the subscription in the old catalog becomes a key in that mapping table to choose the correct Kill Bill `Plan` to use for the creation of the subscription.
  
  
  ==== Billing Dates
  
  Migrating the active subscriptions correctly is definitely one of the challenges of the migration process. Whether the billing happens in arrear or in advance, for each subscription, there is a date up to which it was billed for. This date is referred to as the `chargedThroughDate`:
  
  * When billing in advance, the `chargedThroughDate` is the date in the future where the next invoice will occur (charging for the next period). So `nextBillingDate` = `chargedThroughDate`
  * When billing in arrear, the `chargedThroughDate` is the date in the past (or present) when it was last billed. So `nextBillingDate` = `chargedThroughDate` + 1 period (e.g 1 month)
  
  A clean subscription migration implies that we stop the billing in the old system at the `currentBillingDate` (where `currentBillingDate` + 1 Period = `nextBillingDate`) and starts the billing in Kill Bill at the `nextBillingDate`. So how to achieve that result?
  
  The first mandatory piece is to be able to extract those dates from the old billing system for each individual subscription attached to the account. In some billing systems, there is only some support to have a `billCycleDate` (`BCD`) at the account level (day of the month at which account is billed) and so that simplifies the problem. In some other cases, different subscriptions can have their own individual schedules. Kill Bill supports all models through the use of billing alignments (and for reference, even a `SUBSCRIPTION_BUNDLE` alignment) defined in the catalog. So, the starting point is to verify those alignments match the old system (this was part of the Pre-Requisites section).
  
  From a billing point of view, we want to cancel the old subscription at `currentBillingDate` and start (the billing of) the subscription at `nextBillingDate`.
  
  