Kill Bill — Open-Source Subscription Billing and Payment Platform

Introduction

Kill Bill is an open-source billing and payment platform built in Java. It handles the full lifecycle of subscription management, invoicing, payment processing, and revenue recognition. Originally developed at Groupon to handle millions of transactions, it provides a plugin-based architecture that integrates with any payment gateway or business workflow.

What Kill Bill Does

• Manages subscription plans with trials, add-ons, upgrades, and downgrades
• Generates invoices automatically based on subscription events and usage
• Processes payments through pluggable payment gateway integrations
• Tracks entitlements to control feature access based on active subscriptions
• Provides dunning management for failed payment retry and recovery

Architecture Overview

Kill Bill is a Java application running on an embedded Jetty server with a MySQL or PostgreSQL database. The core platform handles the subscription state machine, invoice generation, and payment orchestration. Business logic is extended through an OSGI-based plugin framework. A REST API exposes all operations, and Kaui (Kill Bill Admin UI) provides a web dashboard for operations teams.

Self-Hosting & Configuration

• Run via Docker or deploy the WAR file on any Java servlet container
• Requires MySQL or PostgreSQL as the backing database
• Install payment plugins for Stripe, PayPal, Adyen, or custom gateways
• Configure catalog XML files to define products, plans, and pricing rules
• Deploy Kaui alongside Kill Bill for a visual admin interface

Key Features

• Flexible catalog system supporting flat, tiered, usage-based, and hybrid pricing
• Plugin architecture with payment, notification, and analytics extension points
• Multi-tenancy support for SaaS platforms serving multiple organizations
• Audit trail and timeline APIs for compliance and debugging
• Built-in support for proration, credits, refunds, and chargebacks

Comparison with Similar Tools

• Stripe Billing — Managed SaaS billing; Kill Bill is self-hosted with full data ownership
• Lago — Open-source usage-based billing; Kill Bill covers broader subscription lifecycle
• Chargebee — SaaS subscription management; Kill Bill is self-hosted and more customizable
• Recurly — SaaS recurring billing; Kill Bill offers plugin-based extensibility
• Zuora — Enterprise billing platform; Kill Bill is open source and avoids vendor lock-in

FAQ

Q: What payment gateways does Kill Bill support? A: Kill Bill supports Stripe, PayPal, Adyen, Braintree, and more through its plugin system. You can also write custom payment plugins.

Q: Can Kill Bill handle usage-based billing? A: Yes. Kill Bill supports usage-based pricing with metered billing records submitted via the API.

Q: Is Kill Bill suitable for high-volume billing? A: Yes. Kill Bill was built at Groupon to process millions of transactions and is designed for horizontal scaling.

Q: Does Kill Bill provide an admin UI? A: Yes. Kaui is a companion Rails application that provides a web-based admin dashboard for managing accounts, subscriptions, and payments.

Sources

• https://github.com/killbill/killbill
• https://docs.killbill.io/