Kill Bill Migration Guide

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:

We identified the minimal state that needs to be migrated and also explored why migrating more is a difficult endeavor. 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:

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 in several batches, making sure we reach a point of convergence:

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:

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:

The migration code consists of several pieces:

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 separate box, but again, this could be implemented in various ways.

As discussed previously, each existing account would be migrated independently from the others providing a small granularity (and avoiding a risky 'success or fail all' type of migration). It is also important to allow for a process that provides clarity on what failed and what succeeded and the ability to restart things from where they failed. In essence, migrating an account should be an idempotent process, so if it fails part way through, things can be resumed. In order to achieve that result, the Migration Framework should own a migration table with the following fields (obviously one could add/remove fields as needed):

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.

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:

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 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.

A naive migration strategy would be to start the subscription in Kill Bill at nextBillingDate. While this works from a billing point of view, this causes some issues when the customer makes some changes (upgrade, downgrade, cancellation,…​) during the interval of time such that cutOverDate <= t < nextBillingDate: In that interval of time, the subscription would have a future startDate (= nextBillingDate) so immediate changes could not be applied. Also, from an entitlement point of view, starting the subscription in the future means there is no service until we reach that date.

So, we need to separate the date at which the subscription starts (subscriptionStartDate) and the date at which the invoicing starts: from an entitlement point of view, we could use the cutOverDate as the subscriptionStartDate, and this would work, but a better choice is to use the originalSubscriptionStartDate (date at which the subscription started in the old billing system). As far as entitlement goes, starting a subscription in the past is equivalent to starting it in the present, so using the Kill Bill subscriptionStartDate = originalSubscriptionStartDate solves the entitlement issue we mentioned above and it also preserves the originalSubscriptionStartDate of the subscription (which can be really useful for customer support when they interact with the customer).

Let’s summarize, the discussion about dates using the diagram below:

At t = cutOverDate, the account is being migrated and for each existing active subscription in the old billing system, we create a subscription by specifying both the entitlementDate = originalSubscriptionStartDate and the billingDate = nextBillingDate.

Note: The subscription apis allow you to specify both the entitlementDate and billingDate. Some examples on how to use those apis to achieve the migration goal can be found here.

For information, it is still interesting to show how things were done prior the introduction of those new apis. The sequence was a bit more complex, but this shows that in very complex scenario there is a lot of flexibility through the use of the BlockingState events. Below is a description of how things could work using BlockingState:

Note that subscription apis to create subscription don’t allow you to specify different dates for billing and entitlement, so additional apis calls to insert the BlockingState are required. While less practical, this is not really an issue because at that stage we have set AUTO_INVOICING_OFF at the account level so nothing will happen and atomicity is not required.

Finally, we should explore a bit more the choice of the per-account cutOverDate: is it better to choose that date close to currentBillingDate or nextBillingDate? A choice of cutOverDate close to currentBillingDate (right after), means that the customer just got invoiced and so the chances for adjustments right after are bigger than if we were to wait. Since we want to minimize actions on the old system after the customer got migrated, it seems a better choice would be to pick cutOverDate right before nextBillingDate. Of course, in situations where customers have multiple subscriptions on different schedules (SUBSCRIPTION billing alignment), there is a choice to be made (probably favor the annual versus monthly and subscriptions on higher Plans).

There is another concern we did not discuss yet when migrating subscriptions for multi-phase Plans. Kill Bill supports Plans with multiple PlanPhases (such as TRIAL, DISCOUNT, EVERGREEN). The old billing system may support that concept as well, or it could be that such concepts are implemented in an entirely different fashion:

There is obviously some amount of work to understand the old system’s model, and how those will translate into the Kill Bill catalog (again part of the Pre-Requisites stage). Assuming we are migrating a subscription into Kill Bill using a multi-phase Plan, we have to be cautious with the entitlement alignments and make sure we end up on the right phase.

One strategy is to define more Plans in the Kill Bill catalog to include mono-phase versions of the multi-phase Plans. For example, assuming a subscription with a 2 phases Plan (TRIAL=15 days, followed by EVERGREEN), we could also create another Plan with only the last phase so as to migrate subscriptions that are already on the EVERGREEN phase.

Alternatively, we could decide to only use the original Plan, and play with subscription alignments in the following way:

Some billing systems also allow you to schedule future changes associated to a subscription (such as upgrading a subscription in the future or cancelling a subscription in the future, …​). During the migration, it is important to keep track of those future changes. Fortunately this is fairly straight-forward using the Kill Bill apis to change Plan or cancel in the future.