Kill Bill

Last reviewed Sep 13, 2026 · 935 words

Most people who search for Kill Bill want an invoicing tool, and Kill Bill is not one. It is the billing engine underneath a SaaS business: plans, trials, proration, usage metering, dunning, tax hooks, payment routing across gateways, and an audit trail of every change to every subscription since 2010. It has no customer-facing portal and its admin UI is a separate Rails app. If you need to send 20 invoices a month, close this tab and look at Crater or Akaunting. If you are replacing Chargebee or Zuora because their percentage-of-revenue pricing has become a line item your CFO notices, keep reading.

"Hard" is a description of the domain, not the software

Kill Bill's difficulty rating comes from what it models. A subscription has a catalog product, a plan, a phase (trial, discount, evergreen), a billing period and an alignment rule, and an entitlement that is distinct from the billing state, so a customer can be cut off from service and still owe money, or keep service while a payment retries. Every one of those concepts exists because some real business needed it, and you will need to understand each before your first invoice is right.

The Java stack is heavy: 2 GB of RAM is a floor, the server is a Jetty application with a plugin runtime, and Kaui, the admin UI, adds a Ruby process. Operationally you run two web apps and a MySQL or PostgreSQL database, and you need to understand the Kill Bill notification queue, which is how it schedules future invoices and retries. It is a platform you operate, in the same sense that Keycloak or GitLab is.

The catalog XML is the whole product

Plans live in an XML catalog, versioned by effective date. A minimal one declares a currency, a product, a plan with a 14-day trial phase followed by a monthly recurring phase at a price, and the rule that says what happens on plan change. You upload it per tenant over the API, and every future version of the catalog is a new file with a later effective date, so existing subscriptions keep the terms they signed up under. That is the feature that separates Kill Bill from a Stripe integration you wrote yourself: price changes, grandfathering and plan migrations are first-class, and the invoices they produce are reproducible.

Tenancy is also built in. Every API call carries an X-Killbill-ApiKey and X-Killbill-ApiSecret pair identifying a tenant, so an agency or a platform can bill several businesses out of one install with isolated catalogs and plugins.

Running it: two containers and a database

The project publishes killbill/killbill and killbill/kaui images, and the official compose file is the correct starting point:

services:
  killbill:
    image: killbill/killbill
    ports: ["8080:8080"]
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
  kaui:
    image: killbill/kaui
    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

Kaui's first login is admin / password; create a tenant, upload a catalog, and you can create an account and a subscription from the UI within an hour. Then change that password and put both apps behind a proxy that is not on the public internet, because Kaui is an admin console with full write access to your revenue.

Payments, plugins and the ecosystem gap

Kill Bill itself never touches a card. Payment plugins for Stripe, Adyen, Braintree and others do, and the routing layer lets you fail over between gateways or split by region. Plugins also cover tax (Avalara, Vertex), email notifications, analytics and an invoice template engine, and you can write your own in Java or Kotlin against the plugin API. The analytics plugin populates reporting tables you point Metabase or Grafana at; there is no dashboard in the box beyond Kaui's per-account views.

The gap is that the community is a few hundred active operators rather than a few hundred thousand, so the Stripe plugin is well maintained and the more exotic ones need a read of the commit history before you depend on them. Companies that run it at scale tend to have one engineer who owns it. That is the real cost, and it is the number to compare against a Chargebee bill.

Lago is the newer sibling

Lago is the other open-source billing engine in the finance category, Ruby and Postgres, with a modern UI and a usage-based-billing focus. It is easier to stand up and nicer to look at, and it is where I would point a startup with metered pricing and no billing history. Kill Bill wins on the depth of the subscription model, on multi-tenancy, on 15 years of edge cases, and on the audit trail. If your plans are simple, Lago; if your plans have grandfathered tiers, add-ons, regional gateways and a finance team that asks how an invoice was computed, Kill Bill.

What I'd do

Only self-host Kill Bill if billing is a core system you are willing to staff, meaning one engineer who reads the catalog documentation end to end and owns upgrades. Start from the official compose file, use PostgreSQL rather than the MariaDB demo image, write your catalog by hand rather than in the Kaui form so it lives in git, and wire the Stripe plugin first. Under about 200 subscriptions with simple plans, pay Chargebee or use Lago; the engineering time costs more than the percentage.