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:

Most 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. This may occur, for example:

After an invoice has been generated, its balance is positive or zero. If it is positive, the customer owes money and needs to pay the balance. Each time an invoice would become negative, the system automatically inserts a special item, called credit balance adjustment (CBA), to bring the balance back 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 the 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 generation).

An invoice is composed of invoice items. 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 prorated.

Payments can be made against existing invoices, either automatically by the system or manually using our apis. By default one payment is applied to pay one invoice in full. Kill Bill also allows multiple partial payments against a given invoice. Using one payment to pay multiple invoices is not (yet) supported.

Payment in full against an invoice happens automatically provided the customer Account has a valid default payment method. However, This behavior will be disabled under the following conditions:

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

The call below illustrates how to make a manual payment against an existing unpaid invoice:

Kill Bill keeps track of the mapping between invoices and payments, so that it can correctly compute the invoice balance, and also return the payment details associated with a given invoice. This mapping, InvoicePayment, is logically part of the invoice subsystem, and is returned when invoices are fetched.

If an invoice doesn’t have a corresponding row in invoice_payments, this means the invoice isn’t paid (because either no payment was ever attempted, or the payment attempts were unsuccessful). There are three types of InvoicePayment: successful payment, payment followed by a refund, and payment followed by a chargeback. Each of these is described below.

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

To accomodate 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. It can be used also 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 the Kill Bill core (see payment control plugin guide). The role of this plugin is to provide the necessary logic to coordinate the payments associated with an invoice:

Note: The plugin linking the payment view to the invoice view is not a standalone plugin; instead it is part of the core Kill Bill source code. However, it acts as a plugin since it implements the PaymentControlPluginApi. It is possible to provide a standalone plugin that would override the behavior of the default plugin, but this should only be done for advanced use cases. 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, such as credit cards, debit cards, or PayPal. In order to allow the system to automatically make payments against unpaid invoices, a default payment method must be specified.

The payment method really has two functions:

Kill Bill also allows the user to configure a special payment method, called external payment method, to allow recording payments that occured outside of the system. For example, a customer may be invoiced through Kill Bill, and later make payment by check. The payment needs to be recorded into the system to mark the invoice as being paid and to bring its balance to zero.

A user would typically create a default external payment as shown below. Later, the returned paymentMethodId could be used to issue external payments against invoices (see Invoice Payment section).

If a payment fails, the plugin may attempt a payment retry. There are two system properties that 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 feature, also referred to as Dunning, which is required 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 regarding her subscription(s):

The Overdue module in Kill Bill relies on a configuration file which drives its behavior. The configuration can be specified at the tenant level, similarly to the catalog, or it can be specified globally for the system using the org.killbill.overdue.uri system property (e.g org.killbill.overdue.uri=file:///<path>/overdue.xml). This property specifies an overdue configuration file overdue.xml. For details on this file see Overdue System. If no file is specified, default values will be used.

The Overdue module listens to payment events, then changes the overdue state for an account to the appropriate state based on the configuration. 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 that a customer’s account may go through if the customer does not pay. 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 parts 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 tells the system when to re-evaluate the state when nothing happens in the system. When an account transitions to one of the overdue states specified by the xml file overdue.xml, two things can happen:

In the first case, the Overdue system will detect that a payment occurred and it will recompute the state, transitioning to 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: