Kill Bill subscription guide

The default behavior of Kill Bill is to run with multi-tenancy enabled. In that mode, one needs to first create a tenant and specify the credentials that will be required subsequently on each call. Each call requires a default username and password that is used in the system for role base access control (RBAC). By default we are using the username 'admin' and its default password 'password'. The first operation is to create the tenant specifying the api key and secret that will need to be provided in each subsequent call:

At this point, test your setup by making sure you can retrieve the default tag definitions:

The next step will be to create an account:

Now, let’s attach a payment method to that account. Since that demo does not have any real payment plugin attached to it, we will choose the default external payment method plugin that comes configured with the system (used to process checks for example). That default payment plugin does not require any payment method details such as Credit Card info, and so the pluginInfo parameter is an empty map:

Note: the payment plugin associated with this payment method will mock all calls, so all payment calls will succeed.

At this point we can create a subscription based on the default demo catalog:

It is interesting to verify that the system immediately invoiced for the subscription that was created. Because the subscription is using a Plan with trial phase of $0, there is no associated payment:

We will now upgrade the plan from the 'Standard' to the 'Sports' product:

At then finally, we will cancel the subscription.

Retrieving the invoices like we did in the previous step would show that a new invoice was automatically created after each change on the subscription. By default Kill Bill reacts to any change happening in the system automatically, creating invoices to match new state and trigerring payments when needed.

In this section we outline some key pieces of terminology that you will need to understand. Different billing systems use these same words to mean subtly different things so, even if you are familiar with the language, it is worth looking though exactly how we use the terms in Kill Bill.

Writing a Kill Bill Catalog involves defining of the following pieces:

The catalog is first used by Kill Bill at the time the user creates a subscription, then subsequently if there is change of Plan (upgrade, downgrade), and then finally when the user cancels the subscription. During such operations, Catalog information is retrieved to make sure the system builds the right subscription (e.g. maybe there is a TRIAL phase to start). Information about how to perform such operations is configured in the catalog through the Subscription Alignment Rules. An overview of some of these rules:

The catalog is also used by the invoicing system to make sure each each Customer is billed at the right time and for the right amount. Information about how the customer is billed and when the customer is billed is also defined in the catalog using alignments and their associated rules.

Catalog configuration allows to define if different subscriptions attached to a customer should be invoiced at the same time, or at the opposite if they should be billed separately on their own schedule (or a mix of both where some are grouped together on the same invoice and others are invoiced independently). In the simplest case, where all subscriptions are grouped together and there is a BCD defined (Billing Period is a multiple of the month), the customer gets one invoice per Billing Period on that (BCD) day. Note that grouping subscriptions together may by default lead to some leading pro-ration when the subscription is started on a different date than the BCD (as the system needs to realign invoicing on that particular date). This behavior is configured in the catalog through the Billing Alignment Rules.

Where do you go from here to learn more:

In this section we look at getting the top level catalog created and configured. Note that the catalog currently requires all attribute strings to be unique, and those strings cannot have space.

The XML document starts in a standard way. The main tag is “catalog”. Within the catalog opening tag you can specify the schema location. You can use the standard schema location (above) or you can have the code generate the current schema by executing: As an example, the killbill-catalog-x.y.z-xsd-tool.jar for the version 0.13.7 can be found here.

The order of content information in the catalog is important. The first tag should be the “effectiveDate” (when the catalog becomes effective), then “catalogName” and then “currencies”, as shown below.

The Product is a representation of the thing the customer is actually buying. Specifying a Product is very straightforward it has the following parameters:

The rules section of the catalog allows the definition of different Kill Bill behaviours for the creation, cancellation and changing of Plans. Here we provide the most simple rule set possible.

Kill Bill requires that there is a defined default rule for each rule type. The rules are applied by matching cases, if there are no case matching a particular situation then the default rule is applied. It is important to have a default rule even if you don’t expect to use it just to ensure that you cover all possible cases.

In this example we specify the following default for the following rule types:

Also, note that those rules define the default behavior, but the APIs also allow to override those behavior on a per call basis.

This tutorial builds on the Basic Tutorial to illustrate the more advanced features of the Kill Bill Catalog. The XML example for this tutorial can be found here.

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.

Kill Bill supports three categories of products:

The terms Base Plan, Add-on Plan and Standalone Plan represent plans that are associated with these three types of product respectively.

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 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 C.I.A. 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 the are in and move to a different one (usually the Default). In the section on rules we explain how to configure these properties.

There 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 Predicate is satisfied by the context, then the Result of that Case is applied.

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

This far in the discussion we have been considering single stand-alone catalogs, but Kill Bill allows the catalog to be modified over time. This is done by creating a set of catalogs with effectiveDates through time. Each catalog is superseded by the next. In this way we can change prices, add new Plans, Products, Price Lists etc, retire Plans, Products, Price Lists etc.

Note that the catalog does not allow the removal of objects. Only additions and certain modifications are allowed. Objects can be retired which means that they cannot be applied to new subscriptions. However existing subscriptions will still refer to them.

An invoice for a subscription on a fixed phase of $0 (trial phase for example) would look like:

An invoice for a subscription on a recurring phase of $20 would look like:

In a case where invoicing occurs in advance, a user gets charged for the upcoming period. For instance a user that subscribed to a monthly plan on 2013-04-11, would get a first invoice, charging for that month. Assuming he paid his invoice, his balance is now 0. Let’s assume he decides to upgrade on 2013-04-26:

Previous invoice:

On the new invoice, the system will generate a REPAIR_ADJ item for the part of the subscription on the old plan that was not used, and a new RECURRING item for the new plan on the remaining period.

Note that if the absolute value of the amount of the REPAIR_ADJ had been greater than the amount of the new RECURRING item, the system would have generated a CBA_ADJ item whose purpose would have been to bring the balance to 0, and provide the customer some credit that would have been used on subsequent invoices.

An invoice item adjustment would look like (assuming the invoice wasn’t paid, otherwise a CBA_ADJ item would be added):

An invoice adjustment would look similar (assuming again the invoice wasn’t paid, otherwise a CBA_ADJ item would be added):

A REFUND_ADJ item would be used instead of CREDIT_ADJ if the invoice was paid and a refund had been issued.

Note that CREDIT_ADJ items are also used to represent credits created by the user (via APIs). In this case, a dummy invoice is created with a negative amount for the CREDIT_ADJ item. This makes the system generate a CBA_ADJ automatically, which in turn can be used as account credits. For example, here is how a $20 credit would be represented:

Here is how a payment, followed by a refund would look like:

Here is how a payment, followed by a chargeback would look like: