Introduction

Kill Bill is an open-source, programmable platform that enables you to build custom billing solutions. Think of it as building blocks to implement your own billing workflows.

Similar to the Unix philosophy of composability over monolithic design, Kill Bill provides APIs to create various pricing models, manage subscriptions, generate invoices, integrate with various payment gateways, etc. Whether you are selling access to a digital service for $10 a month or selling a multi-tier cell-phone data plan, Kill Bill provides the primitives to do it so you don’t have to start from scratch.

Does Kill Bill support per CPU-hour billing? is the wrong kind of question to ask when evaluating Kill Bill. This would be similar to asking Does Spring Boot offer endpoints to store user data?: Spring Boot gives you all the tools you need to create endpoints which can take in user data and let you persist that data in a database, without having to worry about parsing HTTP headers or setting up database connection pooling, but it doesn’t offer a user data endpoint. This is similar in the case of Kill Bill: while it doesn’t understand CPU hour billing, you can create a usage-based plan in the catalog, which is billed based on the number of consumed CPU-hour units.

While Kill Bill is used for various cases (B2B, B2C, offline, etc.), to get a better sense of what Kill Bill offers out of the box, let’s look at how it is used in a typical B2C e-commerce environment.

Kill Bill’s subscription billing features allow an online store to create recurring or usage-based subscriptions (e.g., "Gold plan subscription at $9.99/month") and manage upgrades and downgrades. Kill Bill takes care of generating invoices, managing credits and triggering payments. Netflix, Dropbox, and The New York Times are examples of websites which sell such subscriptions.

Kill Bill’s payment features let the online store connect with virtually any payment gateway and processor (Stripe, Braintree, PayPal, Adyen, etc.) to charge customers (using credit or debit cards, ACH, wire transfers, Bitcoin, etc.) for their subscriptions or one-off payments (e.g., shopping cart-type websites like Amazon or Zappos).

Check this video for a quick tour:

0

Overview

Big Picture

At a high level, we provide two pieces of software that you will have to deploy and manage in your own data center, in your private cloud, or in any public cloud.

  • Kill Bill, or Kill Bill server, is a standalone Java server that runs in your back-end. Your customers will never interact with it directly, but instead your website (it could be a custom website, a Drupal or WordPress deployment, etc.) and potentially your internal tools (CRM, CPQ, etc.) will trigger REST API calls (over HTTP) to create subscriptions, retrieve invoices, give credits, etc.

  • Kaui, our back-office user interface, lets your teams (customer support, product, finance, etc.) interact with Kill Bill to manage refunds, invoice adjustments, reporting, and so forth.

KillBill High level

So, in the diagram above, we can see that:

  • As mentioned earlier, customers interact with your website, which then issues REST API calls to Kill Bill. You are responsible for designing and building that piece.

  • Kill Bill, with its database, manages all the state associated with the subscriptions, invoices, payments, etc.

  • Kaui, the back-office UI for your teams, includes role-based access control to provide different privileges for the various teams/users:

    • Your customer support team uses Kaui to access/modify consumer accounts data.

    • Your product team uses Kaui to configure catalog information, billing rules, etc.

    • Your finance/accounting team access Kaui for different types of reports.

    • Your engineering team access Kaui for running quick scenarios for development and testing purposes.

Deployment

Kill Bill is packaged as a self-contained WAR and is therefore executed within a web container (typically Tomcat). While you can deploy Kill Bill directly as a WAR inside a container, we also provide additional deployment options, such as Docker containers or AWS AMIs with 1-click deployments.

Here is a typical Kill Bill deployment architecture:

KillBill Mid level
  • There are two sets of servers, one for Kill Bill, one for Kaui. Each server can either be a physical server, a VM, or a container. Either way, it will run a Tomcat Java process where Kill Bill or Kaui are deployed. Typically, two instances of Kaui and three of Kill Bill should be plenty.

  • Two (physical or virtual) load-balancers route traffic to the servers (in a least number of connections or round robin configuration). Assuming the network can be trusted, these load-balancers terminate SSL traffic.

  • The Kill Bill and Kaui instances are stateless, but need a relational database. The database server can be shared (but the applications should always use two different schemas) or not.

In a nutshell, a Kill Bill deployment follows a typical microservices deployment. Common DevOps techniques, such as rolling updates, Blue-Green deployments, and Canary deployments, are applicable as well.

To know more, follow our deployment guide.

Kill Bill Platform

We refer to Kill Bill as a platform because of its extensibility: You can write plugins to modify the behavior of the system or to integrate with third-party vendors, such as fraud detection solutions (Accertify, Feedzai, etc.) or tax providers (Avalara AvaTax, Vertex, etc.). We offer some open-source plugins on our GitHub organization, but in order to match your exact business requirements, you may need to write your own.

As an example, let’s imagine a Kill Bill deployment with two plugins, the first one a tax plugin that will interact with a 3rd party tax provider, and the second one, a payment plugin, that will interact with a payment gateway.


KillBill Plugins

These plugins are bundled as JAR files and deployed in the same Tomcat environment as Kill Bill. They can access the full spectrum of Kill Bill APIs, expose custom HTTP endpoints, or even access the database if they need to persist custom state.

Any customization of Kill Bill will often require such plugins to be written. As such, it is not uncommon for deployments with custom business processes to have a couple of these, in addition to connector plugins, which integrate with third-party systems.

Kill Bill Model

Most current billing systems have been designed to be batch-oriented, (i.e., invoice generation and payments are made in batches at specific points in time). We have taken a different approach and have built a system that is event driven, and where operations will happen in sequence.

A typical scenario is one where a subscription gets created (e.g., a customer signs up for a product), which leads to the creation of an invoice, which in turns triggers payment. Reusing our example from above (a deployment with the two plugins), the following would occur:


KillBill Subscription Flow

The flow diagram above highlights some important aspects of the system:

  1. The creation of the subscription will generate a series of internal events that will lead to the generation of the invoice and its associated payment. If needed, this default behavior can also be adjusted (e.g., to generate invoices in batches).

  2. Because of its plugin architecture, it is easy to extend the system by writing plugins. The diagrams above assumes the plugins interact with third-party systems, but of course all the tax logic could, for instance, be implemented in the plugin itself.

  3. Kill Bill offers well defined extension points for these plugins to be highly effective and modify the behavior of the system as needed.

Features

  • Core Foundations

    • High level of integrity and robustness (battle-tested for the past 12+ years in the world’s largest companies)

    • Authentication and role-based access control (RBAC) support integrating with your LDAP, cloud-based identity (Okta and Auth0), etc.

    • A plugin framework where open-source and proprietary plugins can be added to tailor the behavior of the system for your needs and/or to interact with third party systems (CPQ, Tax, ERP, etc.)

    • A robust persistent event bus, that is used both internally and externally (events are visible to plugins and to other services via HTTP push notifications)

    • An auditing framework that keeps track of all the changes that occurred (who?, when?, what?)

  • Core services, each of which exposing its own APIs and publishing bus events, which are consumed by other core services or plugins:

    • Account: Represents the customer (individual or company) subscribing to services and being billed (potentially responsible for other account charges, in the case of hierarchical accounts). An account can have a set of payments methods (credit card, bank account for wire transfers, etc.), a preferred billing day in the month, a preferred local and time zone for localization of communication, etc.

    • Catalog: Captures the definition of products being billed, along with their pricing models (in advance or in arrear, recurring or usage-based, etc.) and bundles (e.g., available add-ons).

    • Entitlement: Captures which services the account has access to.

    • Subscription: Captures which services the account is being billed for.

    • Usage: Records usage units from an external metering system.

    • Invoice: Invoice generation (e.g., based on subscriptions), management (e.g., ability to adjust invoice items or add credits), and presentment (e.g., branded HTML template) for all charges (subscriptions but also one-off charges).

    • Payment: Payment gateways integration for recurring and one-off payments.

    • Overdue: Dunning management (in case of unpaid invoices, for instance).

  • Multi-tenancy: Kill Bill has been designed as a multi-tenant system, meaning you can run multiple logical instances of Kill Bill with a single server and database. (See this blog post, which illustrates some of the use cases.)

  • Plugins

    • Ability to easily connect to third party services

    • Ability to modify behavior of the system to match custom business logic

Where to Start?

Layman’s Next Steps

If you are interested to know more about what Kill Bill is about, the following links will be of interest:

Technical Guides

To quickly get started, create a sandbox account.

When you are ready to start integrating Kill Bill in your environment:

  1. Follow the Getting Started guide

  2. Integrate your application through our REST APIs

  3. Configure Kill Bill to match your own set of requirements:

All of our documentation is hosted in a GitHub repository, so please either submit a PR when obvious things are missing or wrong, or let us know so we can improve it!