Introduction

Kill Bill is the open-source subscription billing and payments platform.

The subscription billing features let you create recurring or usage based subscriptions (e.g. "gold plan subscription at $9.99/month") and manage upgrades and downgrades. The system will take care of generating invoices, managing credits and triggering payments. Netflix, Dropbox and The New York Times are examples of websites which sell such subscriptions.

The payment features let you connect with virtually any payment gateway and processor (Stripe, Braintree, PayPal, Adyen, CyberSource, etc.) to charge your 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).

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, etc.). A lot of open-source plugins are available on our GitHub organization.

Kill Bill is a standalone Java server that runs in your back-end. Your customers will never interact with it directly, instead your website (it could be a custom e-commerce website, a Drupal or WordPress deployment, etc.) will trigger REST API calls (over HTTP) to process subscriptions or orders. We also provide Kaui, the Kill Bill administrative UI, an interface to interact with Kill Bill for your support and finance teams (to manage refunds, invoice adjustments, etc.).

Conceptually, Kill Bill is deployed as such:

  • Customers interact with your custom e-commerce website (in blue), which issues REST API calls to Kill Bill. You are responsible for designing and building that piece

  • Kill Bill (in pink), with its database, manages subscriptions, invoices, payments, etc.

  • Kill Bill interacts with third-party services (in green), such as payment processors like Stripe and PayPal. You are responsible for choosing and signing contracts with these services

architecture

Check this video for a quick tour:

0

The Kill Bill platform

Some of the features of the Kill Bill platform include:

  • Core Foundations

    • High level of integrity and robustness

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

    • A plugin framework where open-source and proprietary plugins can be added to modify the behavior of the system, and/or to interact with third party systems

    • 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

    • Catalog

    • Subscription and entitlement

    • Usage: units recording from metering system

    • Invoice: invoice generation and management (e.g. ability to adjust invoice items) for subscriptions and one-off charges

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

    • Overdue: dunning management (in case of unpaid invoices for instance)

  • Plugins

Contrary to most (SaaS) billing solutions, Kill Bill is not a batch oriented system, but instead, it is driven by events occurring in the system (for example, the creation of a new subscription will create a new event that the invoicing core service will process and as result a new invoice may be created along with a new event, which the payment core service will then process, …​).

Kill Bill is packaged as a WAR and is therefore executed within a web container (typically Tomcat). It offers REST APIs to manage the state associated with accounts, subscriptions, invoices, payments, …​

Kill Bill supports multi-tenancy, 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).

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 start integrating Kill Bill in your environment:

  1. Follow the installation tutorial below

  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!

Installation

Docker is the recommended way to run Kill Bill, both for developers and in production.

If you are not yet familiar with Docker, take a look at the Get Started with Docker guide. It is quite easy to get it up and running, and will greatly simplify the Kill Bill stack setup.

First, make sure docker, docker-machine and docker-compose are installed.

For example, on a Mac:

brew install docker docker-compose docker-machine

Or on Ubuntu:

sudo apt-get install docker docker-compose virtualbox
base=https://github.com/docker/machine/releases/download/v0.14.0 &&
  curl -L $base/docker-machine-$(uname -s)-$(uname -m) >/tmp/docker-machine &&
  sudo install /tmp/docker-machine /usr/local/bin/docker-machine

The next step is to create a Docker machine to run your containers:

docker-machine create -d virtualbox --virtualbox-memory "2048" killbill
eval $(docker-machine env killbill)

Retrieve the IP address of the Docker machine via:

docker-machine ip killbill

We will assume it’s 192.168.99.100 in the rest of this guide.

Next, create a docker-compose.yml file similar to the one below:

version: '3.2'
volumes:
  db:
services:
  killbill:
    image: killbill/killbill:0.20.0
    ports:
      - "8080:8080"
      - "8000:8000"
      - "12345:12345"
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
  kaui:
    image: killbill/kaui:1.0.4
    ports:
      - "9090:8080"
    environment:
      - KAUI_CONFIG_DAO_URL=jdbc:mysql://db:3306/kaui
      - KAUI_CONFIG_DAO_USER=root
      - KAUI_CONFIG_DAO_PASSWORD=killbill
      - KAUI_KILLBILL_URL=http://killbill:8080
  db:
    image: killbill/mariadb:0.20
    volumes:
      - type: volume
        source: db
        target: /var/lib/mysql
    expose:
      - "3306"
    environment:
      - MYSQL_ROOT_PASSWORD=killbill

and run:

docker-compose up

3 containers will start:

  • one for MariaDB (shared database, used by both Kill Bill and Kaui)

  • one for Kill Bill (accessible on port 8080)

  • one for Kaui (accessible on port 9090)

The startup sequence lasts a few minutes. It is ready when you see the message "Kill Bill server has started".

You can log-in to Kaui by going to http://192.168.99.100:9090 (replace with your Docker machine IP address as needed). Default credentials are:

  • username: admin

  • password: password

You can also go to http://192.168.99.100:8080/api.html to explore our APIs.

Using Kill Bill with Kaui

Go to http://192.168.99.100:9090 (update the IP address as needed). You will be prompted for a username and password. Both Kill Bill and Kaui support role based access control (RBAC), where you can configure fine-grained permissions for your users. The default set of credentials is admin/password, which grants full access.

Because Kill Bill supports multi-tenancy (where each tenant has its own data, configuration, etc.), the next step is to create your own tenant. We will assume the api key is bob and api secret lazar in the rest of this guide.

Modifying the catalog

The Kill Bill catalog contains products and plans definitions. This XML configuration file is really powerful and offers various options for handling trials, add-ons, upgrades/downgrades, etc. For more details on its features, read the Subscription Billing manual.

For basic use cases, Kaui also lets you configure simple (subset of what is supported through XML configuration) plans through the UI, so you don’t have to generate the catalog XML manually. This is available on your tenant configuration page, that you can access by clicking on your tenant name at the top right corner of every Kaui page.

For this tutorial, create 2 plans: standard-free (free plan) and standard-monthly (premium plan), associated with a single Standard product (the product category is BASE). We could have just defined standard-monthly, but that way you could make free users subscribe to the free plan. This is useful for reporting for example (to track how long it took to upsell them, etc.)

Note that we haven’t defined any trial period.

multi gateways standard free kaui multi gateways standard monthly kaui multi gateways catalog kaui

Creating your first account

We will assume that users going to your site have to create an account in your system. When they do, you will need to create a mirrored account in Kill Bill.

To do so in Kaui, click the CREATE NEW ACCOUNT link at the top of the page.

Notes:

  • The Kill Bill External key field should map to the unique id of the account in your system (should be unique and immutable). Kill Bill will auto-generate an id if you don’t populate this field

  • There are many more fields you can store (phone number, address, etc.) — all of them are optional. Keep local regulations in mind though when populating these (PII laws, GDPR, etc.).

Adding a payment method

To trigger payments, Kill Bill will need to integrate with a payment provider (such as Stripe or PayPal). Each means of payment (e.g. a credit card) will have a payment method associated with it.

For simplicity in this tutorial, we will assume your customers send you checks. To create the payment method in Kaui, click the + next to Payment Methods on the main account page. The plugin name should be set to __EXTERNAL_PAYMENT__, leave all other fields blank and make sure the checkbox Default Payment Method is checked.

Once you are ready to integrate with a real payment processor (see this tutorial), all you’ll have to do is to create a new payment method for that account. The rest of this tutorial will still apply.

Creating your first subscription

Let’s now try to subscribe a user to the Standard plan. This is the call that would need to be triggered from your website, when the user chooses the premium plan on the subscription checkout page.

In Kaui, click the Subscriptions tab then the + by Subscription Bundles (a subscription bundle is a collection, a bundle, of subscriptions, containing one base subscription and zero or more add-ons). Select the standard-monthly plan in the dropdown. You can also specify an optional (but unique) key to identify this subscription.

Because there is no trial period and because billing is performed in advance by default, Kill Bill will have automatically billed the user for the first month.

You should see the invoice and the payment by clicking on the Invoices and Payments tabs.

Kill Bill will now automatically charge the user on a monthly basis. You can estimate the amount which will be billed at a future date by triggering a dry-run invoice. On the main account page, in the Billing Info section, click the Trigger invoice generation wand (specify a date at least a month in the future).

Using Kill Bill from your application

Now that you are familiar with the basics, the next step is to integrate Kill Bill in your application using our APIs. Our API documentation contains snippets to help you get started.

We also have lots of examples in our Ruby and Java integration tests.

For support along the way, do not open GitHub issues. Instead, reach out to our Google Groups.