Kill Bill subscription guide

Before beginning this guide, you should perform the following preliminary steps:

The catalog is the central configuration object of Kill Bill for all of your Business rules. It contains what the customer buys (products), how the customer pays for a product (plans), change rules, prices, etc.

In practice, the catalog is an XML file: here is a basic example we use in most of our tests and tutorials. We also have a few other examples to get you started here.

Please refer to the Catalog Configuration documentation to make Kill Bill use your own catalog.

The catalog is one of the most complex yet powerful tools provided by Kill Bill.

If you want to validate your catalog, you can use the catalog load-tool (where x.y.z is your current Kill Bill version):

If you see "Success: Catalog loads!", the catalog is valid.

Also, if you need an xsd file, you can find one here or generate one using the catalog xsd-tool:

The Catalog is a data model that captures the core configuration of the billing system. This model is at the heart of the billing system. It is very important that all the business logic associated with the billing behaviour of your system is captured in the billing system. If your billing system is not capable of capturing all of the business logic it ends up being put in multiple places such as your purchase flow, Admin UI, human process etc. It becomes very difficult to keep all these places consistent, and very difficult to make changes when they are needed.

Kill Bill provides a very powerful catalog that, unlike other billing systems, allows the administrator to set up sophisticated business rules around cancellation and plan changes. For example, Kill Bill can just be told to “Cancel” a plan and it will know when to perform the cancel, based on things like the type of plan, or whether it is in trial.

The things you can configure with the Kill Bill catalog include:

Kill Bill also supports the concept of a Price List, which is a grouping of (usually discounted) plans that can be offered to a customer.

Of course, any catalog can only support a limited number of options. When you need to go further, and many people do, you can write plugins to implement pretty much anything you need.

The Product is a representation of the thing the customer is actually buying. Specifying a Product is very straightforward. The product is described by the following parameters:

Plans specify the terms of a subscription contract. Each Plan has a name and refers to the purchase of a single product. The details of a Plan are arranged by phase. In the illustration (right) we are showing a Plan with a 30 day Trial followed by an unlimited recurring or "evergreen" phase.

For each phase of the Plan we need to specify:

Plan, Phase and Usage sections can have a prettyName element which would correspond to the display name (such information is subsequently available on invoice items). This is useful for instance if a product is rebranded to a new name in a subsequent version. Plan names don’t need to be updated.

Note that unlike prettyName, the name elements need to be globally unique in the catalog and must conform to the XML NCName definition. This means that they cannot contain symbol characters like :, @, $, %, &, /, +, ,, ;,, whitespace characters or parentheses, and they cannot begin with a number, dot or minus character.

For our Spy Car catalog example we specify three plans with two phases:

As noted above, Kill Bill supports three categories of products:

The terms BASE, ADD_ON, and STANDALONE represent plans that are associated with these three types of product respectively. Having an explicit representation of Add-On products allows Kill Bill to be configured to only allow purchases of add-ons with particular base plans, and to trigger appropriate cancellations automatically when the base plan changes or is cancelled.

A Subscription Bundle is a collection of subscriptions that correspond to an individual product instance, such as all the subscriptions associated with a single cell phone, or, in our example catalog, all the subscriptions associated with the rental of a Spy Car. Subscription Bundles can either consist of a collection of subscriptions to stand-alone plans or a single Base Plan subscription with zero or more Add-On Plan subscriptions.

The Kill Bill catalog allows you to specify the inclusion and availability of Add-On Products with associated Base Products. For example, suppose that we create some add-on products for our example catalog. Let’s add an OilSlick Product and a RemoteControl Product. Now, let’s discuss the availability and inclusion of these:

If we have this specified in the catalog then Kill Bill knows to disallow certain purchases, e.g. it will not allow the purchase of an OilSlick add-on in a Bundle with a Standard Base Plan. Similarly if the Base Plan in a Bundle containing Super and RemoteControl is downgraded to Standard, Kill Bill knows to automatically cancel the RemoteControl Add-On since it is no longer available. Finally, if the Base Plan of a Bundle containing Sports and OilSlick is upgraded to Super, Kill Bill knows to cancel the OilSlick Plan because its features are already included, by default, in the new Base Plan.

Price Lists are collections of Plans, usually associated with a promotion or discount package. For example, we might offer special rates on our Spy Car rental package for CIA Agents, which offers 33% off for the first 3 months of hire.

To do this, we create plans similar to the ones we have already. They should have the same trial phase and the same evergreen phase, but we insert a new discount phase which, for 3 months, charges the appropriate discount.

In this example we consider only the first of the three additional plans.

Once our additional plans have been created, we can add the new pricelist, after the default price list:

The alignment and price list change rules can be used to specify the behaviour to use when changing pricelists. In the example above, we would expect customers to be able to upgrade and downgrade within the discount phase of the subscription and stay in the discounted price list. We refer to this as a "sticky" price list. Kill Bill can also support "non-sticky" price lists, in which plan changes cause the customer to drop out of the pricelist that they are in and move to a different one (usually the Default). In the section on rules we explain how to configure these properties.

There are several different Rules that can be configured in the Kill Bill Catalog. Each Rule answers a specific question. For example, one of the Rules answers the question "When should this plan change be applied?". Suppose Kill Bill receives a request for a subscription to have its plan upgraded, Kill Bill will check the rules, and based on the current plan, the phase it is in, the new plan etc. Kill Bill can determine whether the transition should happen immediately, or be deferred until later.

Rules consist of a series of Cases. Each Case is represented by a Predicate and a Result. Rules are evaluated against a Context. Each Case is examined in order, and the Predicate for that Case is compared to the Context. If the Context satisfies the Predicate, then Kill Bill applies the Result of that Case.

For example, consider the following rule for the timing of applying a plan change:

In this example there are three cases. The cases are evaluated from first to last and the first case for which the predicate matches the context is the one that is successful.

Consider the following Context:

To evaluate the Rule against this Context, we start by considering Case 1. The predicate in Case 1 requires that PhaseType=TRIAL, but the first line of our context has phaseType set to EVERGREEN, so Case 1 fails. However, when we consider Case 2, all the predicate clauses are satisfied by the above context: phaseType=Evergreen, fromProduct=Sports and toProduct=Standard. So, Case 2 succeeds and the Rule evaluates to "END_OF_TERM".

Notice that the predicates only need to specify the values of some of the fields in the context. Fields that are omitted in a predicate can take any value. For this reason Case 3 is a catch-all Case. It always succeeds because the predicate has no clauses so it will succeed with any Context.

The XML for the above rules is given below:

There are three types of Context:

In the remainder of this section we illustrate each type of rule supported by the system.

Billing alignment is concerned with specifying the day on which a particular subscription is to be billed. If an account has multiple subscriptions it is often desirable that they be billed on the same day.

If the billing period for a subscription is MONTHLY or a multiple of MONTHLY (such as QUARTERLY, ANNUAL, etc.) then we define the Bill Cycle Day (BCD). This is the date on which the billing occurs for that subscription each month. If multiple subscriptions have the same BCD, they may be billed on the same invoice. However, if the BCD for a new subscription differs from its start date, then the initial bill will have to be prorated. This will also occur anytime the BCD for a subscription is changed.

If a BCD falls on a date past the end of a given month, such as April 31, it will be set to the last day of that month.

The Billing Alignment Rules specify the policy for billing alignment for the current subscription. There are three kinds of alignment available:

For example, suppose we have a MONTHLY subscription, billed on the 15th of the month, and we add an ANNUAL subscription. If we start the ANNUAL on the 8th, we have 2 choices:

The next example will align addons with the base plan, monthlies to the Account bill cycle day and annuals to their first billed day. Anything else is aligned with the Account.

This far in the discussion we have been considering single stand-alone catalogs, but Kill Bill allows you to modify the catalog over time. You can do this by creating a set of catalogs, one XML file for each version; the system will rank such files based on their effectiveDate to create the various versions. There is no version number proper; the effectiveDate associated with each catalog XML constitutes the version and the next catalog supersedes the previous one. In this way we can change prices, add new Plans, Products, Price Lists etc, retire Plans, Products, Price Lists, etc.

Note that it is possible to remove entries in subsequent catalog versions. For example, removing a Plan in a new catalog version would prevent future customers from subscribing to that Plan. However existing subscriptions may still refer to it.

The Kill Bill entitlement system offers an API for users to manage their subscriptions. The API allows a user to subscribe to a new product, change to a different product, pause, resume or cancel a subscription. Upon each of those API calls, there are two distinct sets of operations that occur in the system:

The philosophy behind that API is that the user (of the API) should be able to configure the entitlement so that it matches their needs exactly, and let the system compute the billing aspect based on the policies that were configured in the catalog.

Example:

As a general rule, then, the administrator deals with the billing policies, and the user of the API controls the details of its entitlement(s). The entitlement system exposes abstractions that reflect that model:

Previously we laid out the general case where the user of the API controls the entitlement and Kill Bill manages the billing aspect based on configuration policies. Some specific entitlement APIs also allow you to override the billing policies on a per call basis.

The table below shows the possible combinations that the API supports. The columns represent the various entitlement (ENT) policies: Immediate, End of Term, or specific date. The rows represent the possible billing policies, which have the same three choices.

The diagrams below illustrate each entry in the table, for the case when a cancellation occurs on a subscription that was billed in advance:

We can see that in all cases, cancelling a subscription has both an impact on the entitlement and the billing side, but we also see that those two are not necessarily aligned: