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 TRIAL
→ EVERGREEN
) 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 daysTRIAL
period.On january 4th, while the subscription is still in
TRIAL
, the user upgrades to agold-monthly
plan.
As a company offering those plans, you have the choice to define the behavior of such operation:
You may want to restart a full 7 days
TRIAL
period (thePlan
being different, one way want the user to have a fully 7 days period to experiment)You may want to offer the remaining of the
TRIAL
period (4 days left)You may want to skip the
TRIAL
altogether (The user already made up his mind he liked the product and upgraded togold-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.
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.
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.
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.
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.
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.
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).