# Kill Bill

Self-hosted subscription billing and payments with a catalog you define in XML.

Kill Bill is a Java billing server for subscriptions, usage, invoicing, payments across gateways, credits, tax and dunning. Plans, prices and overdue rules are XML documents, and accounts, subscriptions, invoices and payments run through a documented REST API. The Aviate enterprise offer is a separate paid product.

- Capabilities: adaptable, operable
- Vertical: invoicing-finance
- Shape: business-app
- Form factor: api
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/killbill/killbill (Apache-2.0), 5845 stars, last commit 2026-10-28
- Last activity: 2026-10-28
- Page: apps/killbill--killbill.html
- JSON: apps/killbill--killbill.json

## Use it when

- you sell subscriptions or metered usage and want billing logic you own instead of a per-revenue SaaS fee
- you want an agent to create plans, subscriptions and invoices through one REST API

## Gotchas

- Needs a Java server plus MySQL, MariaDB or PostgreSQL; the Docker Compose file on the download page starts Kill Bill, Kaui and MariaDB
- Open source has no support or SLA; Aviate adds a catalog UI, wallet, coupons and support for USD 9,999 per month paid annually with a 12-month minimum, and runs on your own infrastructure
- A catalog uploaded for a tenant overrides the file at org.killbill.catalog.uri, and the docs point multi-tenant setups to the API
- Tax and gateway connections come from separate plugins, each with its own config
- Auth is HTTP basic plus X-Killbill-ApiKey and X-Killbill-ApiSecret headers
- The aviate-mcp server (about 127 tools) ships as part of Aviate, with no public repo, package or hosted endpoint, so open source users call the REST API

## Editions

- Kill Bill (open source): Free, open source
  - source: https://github.com/killbill/killbill
  - container: docker compose up
- Aviate: $9,999 per month, closed source
  - installable: https://killbill.io/aviate

## Adaptable: make it yours

Effort: config-only (8 things to edit)

The catalog (products, plans, prices, trial and discount phases, cancellation and plan-change rules) is an XML document and overdue rules are overdue.xml. A single-tenant setup can load both from the filesystem with org.killbill.catalog.uri and org.killbill.overdue.uri; multi-tenant setups upload them per tenant through the REST API or Kaui, which stores them in the database. Payment retry and invoice behavior is set with org.killbill.* properties in killbill.properties, per-tenant config, or KB_org_killbill_* env vars when org.killbill.server.lookupEnvironmentVariables is true.

- Env vars: KB_org_killbill_payment_retry_days, KB_org_killbill_invoice_dryRunNotificationSchedule, KB_org_killbill_catalog_uri, KB_org_killbill_dao_url
- Config files: killbill.properties, catalog.xml, overdue.xml, shiro.ini
- Prompt files: none
- Accounts you'll need: A payment gateway account, through a plugin such as Stripe or Adyen

## Operable: what an agent can drive

Operability: official. Interface: api at https://apidocs.killbill.io (published by the builder, local).

### Reach (partial coverage)

- Define the catalog (products, plans, prices, trials): reachable. POST /1.0/kb/catalog/xml and /catalog/simplePlan in CatalogResource.java
- Create accounts and subscriptions: reachable. AccountResource.java and SubscriptionResource.java under /1.0/kb/accounts and /1.0/kb/subscriptions
- Record and read usage: reachable. UsageResource.java: POST /1.0/kb/usages, GET by subscription and unit type
- Generate and manage invoices: reachable. InvoiceResource.java, InvoiceItemResource.java, plus charges under /1.0/kb/invoices/charges
- Collect payments through gateways: reachable. PaymentResource.java, PaymentMethodResource.java, PaymentGatewayResource.java, InvoicePaymentResource.java
- Issue credits and handle chargebacks: reachable. CreditResource.java POST /1.0/kb/credits; chargeback paths in JaxrsResource.java
- Configure dunning (overdue rules): reachable. OverdueResource.java: POST /1.0/kb/overdue/xml
- Per-tenant settings and payment plugin config: reachable. TenantResource.java uploadPerTenantConfig and uploadPluginConfig/{pluginName}
- Tax calculation: reachable. Tax plugins run at invoice time: POST /1.0/kb/tenants/uploadPluginConfig/killbill-avatax sets the plugin (avatax README) and POST /1.0/kb/invoices/taxes/{accountId} adds tax items. Rates stay in the tax engine.
- Admin UI (Kaui) screens: not reachable. Kaui is a separate Rails app; an agent does not drive its screens, but they sit on this same REST API, so no billing job is lost

### Before your agent can start

1. Start Kill Bill and Kaui with the Docker Compose file from the getting started guide.
2. Find the default admin login in that guide, and change it before anyone else can reach the server.
3. Create a tenant. Your agent can do this with the admin login through POST /1.0/kb/tenants, or you can use Kaui.
4. Give your agent the tenant's API key and secret. It sends them in the X-Killbill-ApiKey and X-Killbill-ApiSecret headers.
5. If you take payments, set up a gateway plugin and its account yourself.

### What to do about the limits

- Admin UI (Kaui) screens: Kaui is a web app for people, and an agent doesn't drive its screens. It sits on the same REST API, so no billing job is lost. You'll need to do this yourself.

## Code stack

- Languages: Java
- Frameworks: Maven, Jersey (JAX-RS)
- Package manager: maven
- Database: MySQL, MariaDB, PostgreSQL
- Hosting target: docker, tomcat, kubernetes

## Evidence and confidence

- formFactor: README: billing server with a REST API; Kaui is a separate admin UI (confidence 0.9)
- executionModel: no model in the product; billing rules are deterministic (confidence 0.95)
- operability: jaxrs/src/main/java/org/killbill/billing/jaxrs/resources/ in the same repo; docs at apidocs.killbill.io; auth per docs.killbill.io/latest/userguide_configuration.html curl example (confidence 0.9)
- effort: CatalogConfig.java and OverdueProperties.java: org.killbill.catalog.uri and org.killbill.overdue.uri read from the classpath or filesystem; docs userguide_configuration: KB_org_killbill_payment_retry_days is a per-tenant, file or env var setting (confidence 0.85)
- editions: killbill.io/pricing: Aviate 9,999 USD per month, billed annually; killbill.io/llms.txt: 12-month minimum; killbill.io/kill-bill-vs-aviate: Kill Bill and the Aviate plugin run in your infrastructure; open source Apache-2.0 (confidence 0.9)
- active: Latest commit 2026-10-28, tag killbill-0.25.6 the same day; bug fix PRs merged in October. The GitHub Releases page lags at 0.24.22 from 2026-09-29
- reach:  (confidence 0.85)

## Open questions

- aviate-mcp: blog.killbill.io (2026-08-12) says the self-hosted server ships as part of Aviate and only the aviate_* tools need an Aviate login. Whether the kb_* tools can be had without Aviate is not stated, so no mcpServer is recorded
- Provenance not established

## Sources

- https://github.com/killbill/killbill (sourcing:invoicing-finance:github)
- https://apidocs.killbill.io (analysis)