Kill Bill subscription guide

We will assume:

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 (see an example 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 at the heart of the billing system. It is a data model that captures the core configuration 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 that 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 Kill Bill can 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 finite 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 it has the following parameters:

Each Plan has a name and refers to the purchase of a single product. Beyond that the Plans parameters are arranged by phase. In the illustration above 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 item). 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 be conform to the NCName definition (i.e. it cannot contain symbol characters like :, @, $, %, &, /, +, ,, ;,, whitespace characters or parenthesis, and it cannot begin with a number, dot or minus character).

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

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 rule uses the Creation Context and configures type of billing alignment used with a subscription. There are three kinds of alignment available:

Example:

This 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 the catalog to be modified over time. This is done 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 to each catalog XML constitutes the version and 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 it is possible to remove entries in subsequent catalog versions: For example, removing a Plan in a new catalog version would prevent future custom to subscribe to such Plan. However existing subscriptions will still refer to them.

The Kill Bill entitlement system primarily 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 its subscription. Upon each of those API calls there are really two distinct set of operations that occur in the system:

The philosophy behind that API is that the user (of the API) should be able to drive the entitlement so that it matches exactly its needs and let the system computes the billing aspect based on the policies that were configured in the catalog. Example:

So, as a general rule, the administrator deals with the billing policies, and the user of the API controls the detail 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 API allows you to provide the following matrix of combinations:

On the horizontal line, we have the various entitlement (ENT) policies or requested cancel date; on the vertical we have the same policies/requested cancel date for the billing side (BILL):

The diagrams below summarize what happens 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:

Most (all?) billing system are batch oriented: Invoice calculation occurs at certain specific times (often configurable), and the system goes through all accounts and generate the missing invoices. Kill Bill, on the other hand, generates new invoices as soon as there is a change in the system that requires such a new invoice:

After an invoice has been generated, its balance is positive or zero. If it’s positive, the customer owes money and needs to pay its balance. Each time an invoice would become negative, the system automatically inserts a special item, called credit balance adjustment (CBA), to bring back the balance to zero. That credit is automatically added to the account and used on future invoices. If the invoice is paid, a payment is added against that invoice. If that invoice is adjusted later on, a CBA item will be automatically generated and appear on the invoice. Kill Bill invoices are for the most part static, with the exceptions of manual changes (manual credit, charge added on a specific invoice after the generation)

An invoice is made of invoice items and the various types of invoice items are:

Recurring invoice items start and end on the same day of the month. For example, a monthly subscription starting on the 21st will have items for the service period 2012-08-21 to 2012-09-21, 2012-09-21 to 2012-10-21, etc. Fixed items only have a start date and never get pro-rated.

Payments can be made against existing invoices, either automatically by the system or manually by leveraging our apis. Kill Bill allows to have multiple partial payments against a given invoice, but the reverse — i.e one payment spanning multiple invoices is not (yet) supported.

One Payment against one invoice is the default model, and this happens automatically by the system provided the customer Account has a valid default payment method - in which case it used to make the payment. However, one can customize the system on a per Account level to disable this behavior, using the following mechanisms:

Anytime an Account has a positive balance, i.e. at least one Invoice was not (partially) paid, one can use our apis to issue a manual payment against such invoice. Based on what we said earlier, such situation can occur if the system was configured to not make payments or in cases where a payment was issued but failed.

The call below illustrates how to make such a payment — against an existing unpaid invoice 99f91a42-a83f-4d59-b337-9df1b53f79b1:

Kill Bill keeps track of the mapping between invoice and payments, in such a way that it can correctly compute the invoice balance — and also return the payment details associated with a given invoice. Such mapping, InvoicePayment, is logically part of the invoice subsystem, and is returned when one fetches invoices. There exists 3 types of InvoicePayment as described below:

If an invoice doesn’t have any corresponding row in invoice payment, this means the invoice isn’t paid (either because no payment was ever attempted, or the payment attempts weren’t successful).

A successful payment against an invoice would have a single row (of type ATTEMPT):

Kill Bill provides a core payment system, that is used in the subscription billing use case to issue payment requests against the generated invoices.

In order to accomodate for that use case, the payment logic has been split into two pieces:

First, there is a core payment system whose role is to manage the payment states, and route the operation to the correct payment plugin, which in turn interracts with the third party payment gateway. This core payment system is not specific to the subscription billing use case, and can actually be used as a standalone system to provide a layer in front of various payment gateways. For an overview of the payment system in Kill Bill, please check the payment guide.

In order to support the subscription billing use case, and issue payments against existing invoices, there is a payment control plugin embedded into Kill Bill core — see payment control plugin guide-- whose role is to provide the necessary logic to map the payments with the invoice:

Note: The plugin linking the payment view to the invoice view has not been implemented as a standalone plugin, but instead it is part of the core Kill Bill source code. However, it implements the PaymentControlPluginApi so logically it acts as such. It is possible to extend/change the behavior of such plugin by registering a standalone payment control plugin that would override the behavior of that default plugin, but this should only be used for advanced use case and extra caution would be required to not break the contract between the invoicing and payment system.

A PaymentMethod represents an abstraction to identify a way of making payments for a specific Account. Each consumer Account can have several payment methods to allow making payments using different schemes — credit cards, debit cards, paypal,…​ In order to allow the system to automatically make payments against unpaid invoices, one must specify a default payment method.

The payment method really has two functions:

Kill Bill also allows to configure a special payment method, called external payment method, to allow recording payments that occured outside of the system. A typical use case is the one where a customer was invoiced through Kill Bill, and later makes payment by check: The payment needs to be recorded into the system to mark the invoice as being paid — and brings its balance to zero.

One would typically create a default external payment method the following way, and later could use the returned paymentMethodId to issue external payments against invoices — see Invoice Payment section.

Upon payment failure, the plugin may attempt a payment retry: There are 2 system properties, that will control the payment retry mechanism:

Payment retries in Kill Bill are implemented as payment transaction retries: For each retry attempt, the system will create a new PaymentTransaction associated with the same Payment object. Since the paymentMethodId is defined at the Payment level, it means that the same paymentMethodId will be used for each retry. If the goal is to retry with a new payment method, then one needs to create a new Payment associated with the different payment method. If there are ongoing retries scheduled, it is possible to cancel those but this is more for cleanliness, because once a payment has been successful, any other retry would be aborted — the system ensures that there cannot be any double payment.

Kill Bill offers an Overdue (or also referred to as Dunning) feature, which is required for when users don’t pay their bills. In those cases, the merchant needs to take some action and so the feature must be customizable. Note that the Entitlement and Overdue modules in Kill Bill are tied to each other and are there to manage the customer experience with regards to her subscription(s):

The Overdue module in Kill Bill relies on a configuration file which drives its behavior. The file is specifed through the use of the org.killbill.overdue.uri system property. The Overdue module listens to payment events and then, based on the configuration it transitions the overdue state for an account to the appropriate state. Whether the payment was a failure or not, the Overdue module will recompute the state associated with the account and potentially make the transition to another state.

The overdue configuration contains a list of the various states through which a customer who does not pay will go through. Each state has a name and a condition which is evaluated by the Overdue module. Currently the condition to transition to a given state is based on the properties below, and the system will evaluate to true if all the part of the conditions are true:

Additionally, the definition of an overdue state will also specify some ways to alter the behavior of the system:

One can add an externalMessage which can be retrieved by plugins listening to Overdue events, and displayed to the user.

Finally there is an additional property autoReevaluationInterval that tell the system when to re-evaluate the state when nothing happens in the system: When an account transition to one of the overdue state — specified by the xml file (overdue.xml), two things can happen:

In the first case, the Overdue system will detect a payment occurred and it will recompute the state, transitioning the a new state if required. In the second case, however, since there was no trigger, we need a way to tell the overdue system to re-evaluate the state every so often so it can advance into the next state if required. That is what the autoReevaluationInterval property is about.

If you need an xsd file, you can find one here or generate one using the overdue xsd-tool: