# Kill Bill

> Open-source subscription billing platform.

- Category: E-Commerce & Business
- Difficulty: advanced
- Components: killbill, mysql, kaui
- Tags: killbill, billing, subscriptions, payments
- Source: https://docker.recipes/ecommerce/killbill

## Overview

Kill Bill is an open-source subscription billing and payment platform originally developed by Ning to handle complex recurring billing scenarios that traditional payment processors couldn't manage. The platform excels at handling sophisticated billing logic including trials, upgrades, downgrades, prorations, usage-based billing, and complex catalog configurations that enterprise SaaS companies require. Kill Bill separates billing logic from payment processing, allowing businesses to maintain control over their subscription lifecycle while integrating with multiple payment gateways. This Docker stack combines Kill Bill's core billing engine with Kaui (Kill Bill's administrative web interface) and MySQL as the persistence layer. Kaui provides a comprehensive dashboard for managing accounts, subscriptions, invoices, and payments, while MySQL stores all billing data, customer information, and transaction history. The three-tier architecture ensures that billing operations remain fast and reliable even under high transaction volumes. This combination is particularly valuable for SaaS companies, subscription box services, and any business model requiring automated recurring billing with complex pricing structures. Kill Bill's plugin architecture means you can start with basic credit card processing and gradually add sophisticated payment methods, dunning management, and revenue recognition as your business scales. The platform handles edge cases like partial refunds, subscription transfers, and complex proration scenarios that often break simpler billing solutions.

## Features

- Advanced subscription lifecycle management with support for trials, upgrades, downgrades, and complex proration calculations
- Flexible catalog system supporting multiple pricing models including flat-rate, tiered, usage-based, and hybrid billing structures
- Plugin architecture with pre-built integrations for Stripe, Adyen, PayPal, and other major payment gateways
- Comprehensive dunning management with customizable retry logic and payment failure handling workflows
- Multi-tenant architecture supporting multiple business units or white-label scenarios within a single deployment
- Advanced invoice generation with customizable templates, line-item breakdowns, and automatic tax calculation support
- Real-time analytics and reporting through Kaui's dashboard with subscription metrics, churn analysis, and revenue tracking
- REST API with comprehensive webhook system for integrating billing events into external systems and business intelligence tools

## Use cases

- SaaS companies with tiered pricing plans requiring automated upgrade/downgrade handling and usage-based billing components
- Subscription box services needing flexible billing cycles, seasonal adjustments, and inventory-linked subscription management
- Enterprise software vendors requiring complex contract billing with custom terms, annual prepayments, and mid-cycle adjustments
- Digital content platforms managing freemium models with trial periods, feature-based upgrades, and usage metering
- Managed service providers billing for infrastructure usage, support tiers, and add-on services with detailed invoice breakdowns
- Multi-brand organizations needing centralized billing infrastructure with tenant isolation and brand-specific payment processing
- Fintech companies building billing capabilities into their platforms while maintaining PCI compliance and payment gateway flexibility

## Prerequisites

- Minimum 2GB RAM available for the full stack, with 1GB dedicated to Kill Bill and 512MB for MySQL operations
- Basic understanding of subscription billing concepts including proration, dunning, and payment gateway integration workflows
- Ports 8080 and 9090 available on the host system for Kill Bill API and Kaui web interface access
- Familiarity with XML catalog configuration for defining products, plans, phases, and pricing rules in Kill Bill
- MySQL administration knowledge for backup procedures, performance tuning, and troubleshooting database connectivity issues
- SSL certificates and reverse proxy setup knowledge for production deployments handling sensitive payment data

## docker-compose.yml

```yaml
services:
  killbill:
    image: killbill/killbill:latest
    container_name: killbill
    restart: unless-stopped
    environment:
      KILLBILL_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
      KILLBILL_DAO_USER: ${DB_USER}
      KILLBILL_DAO_PASSWORD: ${DB_PASSWORD}
    ports:
      - "8080:8080"
    depends_on:
      - mysql
    networks:
      - killbill

  kaui:
    image: killbill/kaui:latest
    container_name: kaui
    environment:
      KAUI_CONFIG_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
      KAUI_CONFIG_DAO_USER: ${DB_USER}
      KAUI_CONFIG_DAO_PASSWORD: ${DB_PASSWORD}
      KAUI_KILLBILL_URL: http://killbill:8080
    ports:
      - "9090:8080"
    depends_on:
      - killbill
    networks:
      - killbill

  mysql:
    image: mysql:8.0
    container_name: killbill-mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: ${DB_NAME}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - killbill

volumes:
  mysql_data:

networks:
  killbill:
    driver: bridge
```

## .env

```bash
DB_ROOT_PASSWORD=rootpassword
DB_NAME=killbill
DB_USER=killbill
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.killbill.io/
- API at http://localhost:8080, Kaui admin UI at http://localhost:9090
- Default login: admin/password - change immediately
- Create catalog XML for products, plans, and pricing rules
- Supports complex billing: trials, add-ons, usage, proration
- Plugin architecture for payment gateways (Stripe, Adyen, PayPal)

## Troubleshooting

- Kill Bill fails to start with database connection errors: Verify MySQL container is fully initialized before Kill Bill starts, add healthcheck or increase startup delay
- Kaui shows 'Unable to connect to Kill Bill' error: Check that KAUI_KILLBILL_URL points to the correct container name and port, verify network connectivity between containers
- MySQL container exits with 'disk space' errors during initialization: Increase available disk space and ensure mysql_data volume has proper permissions for database files
- Kill Bill API returns 500 errors on catalog operations: Validate XML catalog syntax and ensure all required catalog elements (products, plans, price lists) are properly defined
- Payment plugin registration fails with classpath errors: Verify plugin JARs are properly mounted and compatible with the Kill Bill version, check plugin configuration in system properties
- Subscription operations fail with 'clock drift' errors: Synchronize system time across containers and ensure Kill Bill clock settings match your timezone requirements

