Architecture

How Kill Bill Works

The architecture of the open source billing platform, explained with diagrams: where it sits in your stack, what is inside, how events flow, and how it scales.

Last updated: October 2026

See the diagrams
Technical docs
Short answer

How is Kill Bill built?

Kill Bill is a Java server with a REST API that you run in your own infrastructure, on a relational database. Inside, independent core services such as subscription, invoice and payment exchange events on a persistent bus. Java plugins connect payment gateways and tax engines. Nodes are stateless, and one deployment can host several tenants.
Type
Java server you run yourself, with a REST API
Design
Event-driven core services on a persistent bus
Data
Relational database: MySQL, PostgreSQL, MariaDB
Extensions
Java plugins: payment, tax, invoice, catalog and more
Scaling
Stateless nodes behind a load balancer
Isolation
Multi-tenant: several businesses on one deployment
The big picture

Where Kill Bill Sits in Your Stack

Your customers never see Kill Bill. Your applications call it, your teams use Kaui, and Kill Bill talks to payment and tax providers for you.

Think of it asthe billing engine behind your website, the way a payment terminal sits behind a shop counter.

YOUR SIDE Website and appSign-up, plan changes Internal toolsCRM, ERP, data Your teamsSupport, finance, product YOUR INFRASTRUCTURE Java server, REST API Plugins: payment, tax KauiAdmin UI in the browser Database MySQLPostgreSQLMariaDB OUTSIDE SERVICES Payment gatewayStripe, Adyen, Braintree Tax engineAvalara, Vertex, Kintsugi Your systemsReceive events by HTTP REST API Push notifications
Inside Kill Bill

Five Layers, From API to Database

Kill Bill is built as independent core services with their own APIs, on shared foundations, extended by plugins.
REST APIJSON over HTTP, used by your apps, Kaui and Aviate
PluginsJava, isolated from each other (OSGi)
PaymentTaxFraud and routingNotificationsAviate
Core servicesEach with its own API, each publishing events
AccountThe customer, payment methods, billing day, time zone
CatalogProducts, plans, prices, rules
EntitlementWhat the customer can use
SubscriptionWhat the customer is billed for
UsageUnits recorded for usage billing
InvoiceInvoices, adjustments, credits
PaymentCharges and refunds through gateways
OverdueDunning when invoices are unpaid
Foundations
Persistent event busFuture notificationsAudit logUsers, roles and permissionsMulti-tenancyPlugin framework
Relational databaseAll state, events and history
MySQLPostgreSQLMariaDB
Event-driven

What Happens When a Customer Subscribes

No overnight batch: each step publishes an event, and the next step reacts to it. Events are stored in the database, so none is lost if a server restarts.
  1. Your appCreates a subscriptionOne REST API call
  2. SubscriptionRecords it and publishes an eventEvent on the bus
  3. InvoiceComputes what is dueInvoice items
  4. Tax pluginAdds tax lines from the tax engineAvalara, Vertex, Kintsugi
  5. PaymentCharges the default payment methodPayment event
  6. Payment pluginCalls the gateway and returns the statusStripe, Adyen, Braintree
  7. Your systemsReceive the events they registered forPush notifications

Invoices can also be grouped when you prefer one invoice per period for several subscriptions.

Plugins

Change Behavior Without Changing the Core

Plugins are Java modules that run inside Kill Bill, isolated from each other. They can call every Kill Bill API, add their own HTTP endpoints and store their own data.
Payment plugins

Connect a payment gateway or processor.

Stripe, Adyen, Braintree, GoCardless
Invoice plugins

Change invoice items before they are saved, for example to add tax.

Avalara, Vertex, Kintsugi
Payment control plugins

Stop a payment for fraud, or route it to another gateway.

Retries, routing, fraud checks
Catalog plugins

Replace the XML catalog with your own catalog engine.

Aviate catalog
Entitlement plugins

Add your own logic when a subscription is created or changed.

Coupons, price overrides
Currency plugins

Provide exchange rates for payments in another currency.

Currency conversion
Notifications plugins

React to any event: send an email, update a CRM.

Email notifications, analytics
Multi-tenancy

Several Businesses on One Deployment

A tenant is a separate space with its own catalog, settings, data and API key. One server and one database can host many.

Think of it asan apartment building: shared walls and plumbing, separate keys.

Kill BillOne deployment, one database
Tenant: Brand AOwn catalog and pricesOwn settings and templatesOwn API key and secret
Tenant: Brand B, EuropeOwn catalog and pricesOwn settings and templatesOwn API key and secret
Tenant: TestSafe place to try changesSame server, separate dataOwn API key and secret
Deployment

Stateless Nodes, One Database

Kill Bill and Kaui run as Java web applications. Because the nodes keep no state, you scale by adding nodes and update them one at a time.
Your appsREST API calls Your teamsBrowser Load balancer Load balancer Kill Bill node 1 Kill Bill node 2 Kill Bill node 3 Kaui node 1 Kaui node 2 Relational databaseOne schema for Kill BillOne schema for Kaui Nodes are stateless: add or replace one at any time.
TomcatDockerKubernetesJavaMySQLPostgreSQLMariaDB

Typical production setup from the deployment guide: three Kill Bill instances and two Kaui instances are usually plenty.

Security and audit

Who Can Do What, and Who Did What

Users, roles, permissions

Each user has roles, and each role a list of permissions. Users can live in Kill Bill or in your directory.

Okta, Auth0, LDAP
Audit log

Every change records who made it, when, and why, with an optional reason and comment.

Who, when, what
History

Kill Bill keeps the history of each record, and of each event once it is processed.

History tables
Your data stays with you

Kill Bill runs in your infrastructure, on your database, under your security rules.

Self-hosted
Aviate

Where Aviate Fits

Aviate is a plugin installed on each Kill Bill deployment, plus a Control Plane to manage them all. Same database, same APIs. If you stop Aviate, Kill Bill keeps running.
Aviate Control PlaneOne interface for every deployment: catalog, plugins, tenants, settings, templates, health
Kill BillProductionAviate plugin
Kill BillStagingAviate plugin

Kill Bill vs Aviate: what each one includes.

Related pages

Kill Bill API and Client Libraries The Kill Bill REST API: authentication, a first call in six languages, calls from catalog to invoice, client libraries, webhooks and the MCP server. Billing Plugins, API and Integrations Extend Kill Bill with Java plugins for payments, tax and notifications, integrate through the REST API and push notifications, without forking the core. Enterprise Billing Operations and Scale Run Kill Bill on your own infrastructure: stateless clusters, multi-tenancy and usage billing. Aviate adds health monitoring and Level 3 support. Kill Bill Overview: Open-Source Billing and Payments Kill Bill is an open-source billing and payments platform under Apache 2.0, in production since 2010. Self-host it, extend it with plugins, keep your data.
FAQs

Frequently Asked Questions

How does Kill Bill work?
Kill Bill is a Java server that you run in your own infrastructure, with a relational database. Your applications call its REST API to create customers and subscriptions. Kill Bill then generates invoices and collects payments on its own, through event-driven core services and plugins that connect to payment gateways and tax engines.
Is Kill Bill event-driven?
Yes. Each core service, such as subscription, invoice or payment, publishes events on a persistent bus stored in the database. Other services and plugins react to them. Creating a subscription leads to an invoice, which leads to a payment, without batch jobs. Invoicing can also be grouped when needed.
Which databases does Kill Bill support?
The Kill Bill team uses MySQL for most production deployments and for testing, and also runs regression tests against MariaDB and PostgreSQL. Users run Kill Bill on compatible engines such as Percona and Amazon Aurora.
How does Kill Bill scale?
Kill Bill nodes are stateless, so you run several of them behind a load balancer and add more as needed. A typical production setup has three Kill Bill instances and two Kaui instances, sharing a database. Rolling updates and blue-green deployments work as usual.
What are Kill Bill plugins?
Java modules that run inside Kill Bill, isolated from each other. Payment plugins connect gateways, invoice plugins can add tax lines, payment control plugins can stop or reroute payments, and notification plugins react to any event. Plugins can also add their own HTTP endpoints and database tables.
Is Kill Bill multi-tenant?
Yes. One Kill Bill deployment and database can host several tenants, each with its own catalog, settings, templates, data and API key. Companies use tenants for brands, regions, legal entities or test environments.
How are access and changes controlled?
Kill Bill has users, roles and permissions, stored in Kill Bill or connected to LDAP, Okta or Auth0. Every change is recorded in an audit log with who made it and when, and Kill Bill keeps the history of each record.
Where does Aviate fit in the architecture?
Aviate is a Java plugin installed on each Kill Bill deployment, plus a Control Plane that manages one or more deployments from the browser. It uses the same database and the same APIs, and Kill Bill keeps running if you stop Aviate.
Kill Bill logo

Review your billing architecture with us

Run Kill Bill locally with Docker, try Aviate in the sandbox, or talk to the team about your setup. A technical member of the team will reply.
Talk to the team
Download Kill Bill