This version of Kill Bill is not supported anymore, please see our latest documentation

Overview

In the Kill Bill model, Subscriptions are associated to a Plan (defined in the catalog), and Plans are made of several PlanPhases. The idea behind the model is to accurately represent the transitions from different phases (e.g TRIALEVERGREEN) without having the system/user to take any actions: Subscriptions automatically transition from one PlanPhase to the next, as defined by the shape of the Plan and the clock moving forward.

When changing the Plan associated to a subscription (e.g upgrade), the system needs to understand how to align phases from original Plan to new Plan to make sure the user ends up in the right phase. Let’s consider the following example with two similar Plans (silver-monthly and gold-monthly) both containing two phases, namely a 7 days TRIAL phase, followed by a monthly EVERGREEN (recurring forever until cancelled) phase.

  • On january 1st, subscription is initially created with a silver-monthly Plan, and starts with the 7 days TRIAL period.

  • On january 4th, while the subscription is still in TRIAL, the user upgrades to a gold-monthly plan.

As a company offering those plans, you have the choice to define the behavior of such operation:

  1. You may want to restart a full 7 days TRIAL period (the Plan being different, one way want the user to have a fully 7 days period to experiment)

  2. You may want to offer the remaining of the TRIAL period (4 days left)

  3. You may want to skip the TRIAL altogether (The user already made up his mind he liked the product and upgraded to gold-monthly so he is already committed).

In order to provide this level of flexibility, the catalog contains alignement rules to specify such behaviors.

Such alignement rules exist both for operations that create Subscription (to decide on how to align Add-On Plan with respect to the Base Plan) and also, as mentionned in the previous example for change Plan operations. The Kill Bill Subscription Guide provides an overview of such alignments.

In addition to specifying alignment policies, our apis also allow to specify a target PlanPhase. The specification of such target PlanPhase can be used when creating a new Subscription or when changing Plan. With the previously defined gold-monthly plan, we could create a subscription with a target PlanPhase set to EVERGREEN to make sure the user skips the TRIAL phase and directly starts on EVERGREEN phase. Note that this is also achievable by creating more Plan entries in the catalog (e.g a gold-monthly-notrial Plan), but this would force administrators to duplicate the plans and may also be an issue from an analytics point of view (depending on which/how metrics are being computed).

The rest of this documentation will look at various scenarii to understand the impact of Plan alignment and ability to skip PlanPhase.

Scenarii

Subscription Creation with Target PlanPhase specified

In this section we look at the behavior of the system when a change Plan operation happens on a Subscription for which initial phase(s) were skipped at creation (by specifying a target PlanPhase).

Scenario 1a

In this scenario, the Plan for the original Subscription was made of 2 PlanPhases, namely a TRIAL and an EVERGREEN phase, and the user skipped the TRIAL by specifying the EVERGREEN target PlanPhase. Later, a change of Plan to another Plan containing one or more PlanPhase happens, with its (last) PlanPhase being EVERGREEN and the catalog was configured to use a START_OF_SUBSCRIPTION (or START_OF_BUNDLE) plan change alignment.

PlanAlignmentScenario1a

We can see that we realigned based on the date of the start of Subscription and matched the same target PlanPhase that was originally specified when creating the Subscription.

Scenario 1b

This scenario is similar to the previous one except for the catalog that was configured to use a CHANGE_OF_PLAN plan change alignment.

PlanAlignmentScenario1b

We can see that we realigned based on the date of the change Plan operation and we ignore the original target PlanPhase that was originally specified when creating the Subscription. We will see in a subsequent scenario that if the intent is to stay on EVERGREEN we can also specify a target PlanPhase when making the change operation.

Scenario 2a

In this scenario, the Plan for the original Subscription was made of 2 PlanPhases, namely a TRIAL and an EVERGREEN phase, and the user skipped the TRIAL by specifying the EVERGREEN target PlanPhase. Later, a change of Plan to another Plan containing one or more PlanPhase happens, but such Plan does not include an EVERGREEN PlanPhase (the original target PlanPhase specified at creation time). The catalog was configured to use a START_OF_SUBSCRIPTION (or START_OF_BUNDLE) plan change alignment.

PlanAlignmentScenario2a

We can see that we realigned based on the date of the start of Subscription but because the original target PlanPhase does not exist in the Plan we realigned using the first PlanPhase of the new Plan.

Scenario 2b

This scenario is similar to the previous one except for the catalog that was configured to use a CHANGE_OF_PLAN plan change alignment.

PlanAlignmentScenario2b

We can see that we realigned based on the date of the change Plan operation and also start from the first PlanPhase of the new Plan.

Plan Change with Target PlanPhase

In this section we look at the behavior of the system when the user specifies a target PlanPhase on a change Plan operation.

Scenario 1a

In this scenario we assume that a Subscription was created using a Plan made of 2 PlanPhases, namely a TRIAL and an EVERGREEN phase, and the user did not skip any PlanPhase. Subsequently, the user issues a change Plan operation with a new Plan that has 3 PlanPhases, namely a TRIAL, a DISCOUNT and an EVERGREEN phase. The user specifies a DISCOUNT target PlanPhase when changing the Plan. The catalog was configured to use a START_OF_SUBSCRIPTION (or START_OF_BUNDLE) plan change alignment.

PlanAlignmentScenarioChange1a

We can see that we realigned based on the date of the start of Subscription and because the change Plan operation specified a DISCOUNT target PlanPhase, we realign based on that PlanPhase.

Scenario 1b

This scenario is similar to the previous one except for the catalog that was configured to use a CHANGE_OF_PLAN plan change alignment.

PlanAlignmentScenarioChange1b

We can see that we realigned based on the date of the change Plan operation and also start with the specified DISCOUNT target PlanPhase.

Summary

The use of aligment rules (as configured in the catalog) along with the ability to specify target PlanPhase when creating a Subscription or changing the Plan of an existing Subscription provides users with a lot of flexibility.

This documentation has shown some basic scenarii that should provide the knowledge to achieve the desired result. However, the number of use cases to cover is quite large, and dependent of each catalog and business logic, so we strongly advise to experiment (and write tests specifc to each use case).