killbill/killbill: an open source subscription billing and payments platform in Java

What killbill/killbill is for, and who ends up running it

The repository describes itself as an open source subscription billing and payments platform. The problem it addresses is the recurring one: a business sells subscriptions, and then has to track who is entitled to what, when to charge them, what happens when a payment fails, and how to produce financial reports from all of it. Kill Bill puts that logic in a platform you host rather than in a vendor's system. The README frames the benefit in terms of control: because you run the stack, you are not depending on a third party's uptime or processing speed, and you avoid vendor lock-in on your business and client data.

The audience is narrower than the tagline suggests. This is Java software assembled from Maven modules, and the top-level entries in the repository read like a list of billing concerns rather than an application: account, catalog, entitlement, invoice, payment, subscription, usage, overdue, currency, tenant, junction, jaxrs, beatrix, util. Someone evaluating Kill Bill is usually an engineer or a platform team at a company that has outgrown a simple payment integration and wants the billing model itself to be theirs. The README is explicit that this is not an all-in-one product: it is modularized so you can disable functionality you do not need or replace it with an existing system of your own.

The module layout is the architecture

The clearest description of how Kill Bill works is the directory listing. Each top-level module owns one part of the billing domain. account holds customer accounts. catalog holds the products, plans and pricing rules that subscriptions are built from. subscription and entitlement cover what a customer has signed up for and what they are allowed to use. invoice turns subscription state into charges. payment handles the money movement. usage covers metered billing. overdue handles the collections problem: what to do when an invoice is not paid. currency and tenant are further modules.

That split matters for adoption because it is also the failure surface. A billing platform that separates entitlement from invoicing means a bug in one module can produce a customer who is entitled to a service but never invoiced for it, or the reverse. The modularity that the README presents as flexibility is the same property that makes the system harder to reason about than a single billing service. If you plan to replace one module with an existing system, you are taking on the contract between that module and the rest, and the README does not describe those contracts. The technical documentation lives on docs.killbill.io, with sources in the killbill/killbill-docs repository, which is where the module boundaries are actually explained.

Installing Kill Bill and getting to a first invoice

The README does not give a local install procedure inline. It points to docs.killbill.io for technical documentation, apidocs.killbill.io for the REST API, and a getting started guide at docs.killbill.io/latest/getting_started.html that it says runs Kill Bill locally in minutes.

For a self-hosted instance, the repository is a Maven project rooted at pom.xml, so the build path is the usual one for a multi-module Java project.

Where Kill Bill is the wrong tool

The most direct limitation is operational. The README's pitch is that you do not rely on a third-party SaaS provider's uptime. The other side of that sentence is that the uptime is now yours. A billing system that invoices customers on a schedule and moves money has a failure mode that a marketing site does not: a failed run is not a blank page, it is a missed charge or a duplicate one. Nothing in the README describes rollback, replay or reconciliation tooling for a bad billing run, and the documentation it points to is where you would have to confirm that.

The second limitation is scope. Kill Bill is a billing and payments platform, not a payments processor. It handles the billing model, the invoices and the payment orchestration, but the README does not claim to be a gateway. You still need a payment provider underneath, and the choice of that provider is outside what this repository describes.

The third is the modularity itself. If your billing needs are simple, a recurring charge against a card, the account/catalog/subscription/invoice/payment/overdue split is more machinery than the problem requires. The README says the platform can be adopted one business area at a time, which is a reasonable migration story, but it also means you are running a subset of a system whose modules were designed to work together.

How it compares with a hosted billing service

The real alternative for most teams is a hosted subscription billing service, where the billing logic, the invoice generation and the dunning emails live behind someone else's API. The difference in approach is not feature parity, it is where the state lives. With a hosted service you call an API and read back what it decided; with Kill Bill the decision logic is in modules you run, and the invoice and entitlement records are in your own database.

That difference shows up in two places. First, customization: the README says plugins let you extend Kill Bill and connect payment gateways and tax engines without forking the core, and the module layout backs that up, since replacing or disabling a module is a supported idea rather than a fork. A hosted service gives you configuration options and webhooks instead. Second, cost structure: the README states that the project requires financial backing to sustain maintenance and enhancement, and points to GitHub Sponsors for companies, individual users and contributors. The README also describes Aviate, an enterprise version with a commercial license and Level 3 support. If you need a vendor to be accountable for billing correctness, that is a different relationship than sponsorship.

Licence, governance and the cost of staying current

Kill Bill is licensed under Apache License 2.0, stated in the README and present as the LICENSE file at the repository root. Apache-2.0 is a permissive licence, so the practical implication is that you can run and modify the platform without a copyleft obligation on your own code, but the usual Apache-2.0 conditions still apply and this is not legal advice. Check the LICENSE file and the NOTICE conventions your organisation requires before shipping.

Governance is worth reading carefully. The README states that The Billing Project, LLC owns the Kill Bill codebase and trademarks, and that the project was founded independently in 2010 by Martin Westhead, Pierre-Alexandre Meyer and Stéphane Brossier. The project is free to use, and funding comes through sponsorship and the Aviate enterprise offer, which includes a commercial license. That is a coherent model, but it means the maintenance you depend on is tied to sponsorship and support revenue, not to a subscription you pay for.

On upgrade cost, the repository is a multi-module Maven project, so a version bump is a rebuild across the modules you use, not a binary swap. The release history shows a steady cadence of patch releases in the 0.24 line through 2026, and the NEWS file at the repository root is where the project records what changed between them. The last push to the default branch was on 2026-10-28.

Editorial conclusion

Adopt killbill/killbill if you need subscription billing logic you can run and extend yourself, and you have Java engineers who can operate a multi-module service. Do not adopt it if you want a single installable binary, or if hosted billing is acceptable and you would rather not run the stack. Before committing, verify that the modules you need are present in the repository layout you plan to build, and read the getting started guide the README links.

Frequently asked questions

Official sources

1. killbill/killbill on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases