From c7f45b14cc92560d0096233743ffbd542eecbc8b Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Fri, 17 Jul 2026 11:44:23 +0530 Subject: [PATCH 1/4] work for ts 284 --- latest/llms.txt | 122 ++++++++++++++++++ latest/skill.md | 329 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 451 insertions(+) create mode 100644 latest/llms.txt create mode 100644 latest/skill.md diff --git a/latest/llms.txt b/latest/llms.txt new file mode 100644 index 000000000..c452a662d --- /dev/null +++ b/latest/llms.txt @@ -0,0 +1,122 @@ +# Kill Bill Documentation + +> Official documentation for Kill Bill, Kaui and plugins. + +## Understand Kill Bill and Getting Started with Kill Bill + +- https://docs.killbill.io/latest/what_is_kill_bill.html +- https://docs.killbill.io/latest/features.html +- https://docs.killbill.io/latest/premium_features.html +- https://docs.killbill.io/latest/demo.html +- https://docs.killbill.io/latest/faq.html +- https://docs.killbill.io/latest/Kill-Bill-Glossary.html +- https://docs.killbill.io/latest/getting_started.html +- https://docs.killbill.io/latest/killbill-changelog.html +- https://github.com/killbill/killbill/releases +- https://github.com/killbill/killbill-admin-ui-standalone/releases +- https://docs.killbill.io/latest/quick_start_with_kaui.html +- https://docs.killbill.io/latest/quick_start_with_kb_api.html +- https://docs.killbill.io/latest/stripe_plugin.html +- https://docs.killbill.io/latest/userguide_subscription.html +- https://docs.killbill.io/latest/userguide_payment.html +- https://docs.killbill.io/latest/internationalization.html +- https://docs.killbill.io/latest/migration_guide.html + + +## Deploy, Operate and Integrate + +- https://docs.killbill.io/latest/userguide_configuration.html +- https://docs.killbill.io/latest/userguide_deployment.html +- https://docs.killbill.io/latest/deploy_to_kubernetes.html +- https://docs.killbill.io/latest/how-to-upgrade-the-database.html +- https://docs.killbill.io/latest/PostgreSQL.html +- https://docs.killbill.io/latest/user_management.html +- https://docs.killbill.io/latest/how-to-use-kpm-diagnostic.html +- https://apidocs.killbill.io/ +- https://docs.killbill.io/latest/swagger_documentation.html +- https://docs.killbill.io/latest/postman.html +- https://docs.killbill.io/latest/push_notifications.html +- https://docs.killbill.io/latest/kill_bill_events.html +- https://docs.killbill.io/latest/java_client.html +- https://github.com/killbill/killbill-client-ruby +- https://github.com/killbill/killbill-client-php +- https://github.com/killbill/killbill-client-js +- https://github.com/killbill/killbill-client-python +- https://github.com/killbill/kbcli +- https://docs.killbill.io/latest/debugging.html + +## Plugins + +- https://docs.killbill.io/latest/plugin_introduction.html +- https://docs.killbill.io/latest/plugin_development.html +- https://docs.killbill.io/latest/plugin_installation.html +- https://docs.killbill.io/latest/plugin_management.html +- https://docs.killbill.io/latest/plugin_use_cases.html +- https://docs.killbill.io/latest/email-notification-plugin.html +- https://docs.killbill.io/latest/userguide_analytics.html +- https://docs.killbill.io/latest/avatax-plugin.html +- https://docs.killbill.io/latest/braintree-plugin.html +- https://docs.killbill.io/latest/notification_plugin.html +- https://docs.killbill.io/latest/payment_plugin.html +- https://docs.killbill.io/latest/payment_control_plugin.html +- https://docs.killbill.io/latest/usage_plugin.html +- https://docs.killbill.io/latest/invoice_plugin.html +- https://docs.killbill.io/latest/catalog_plugin.html +- https://docs.killbill.io/latest/entitlement_plugin.html +- https://docs.killbill.io/latest/custom-email-invoice-formatter.html + +## Tutorials and Examples + +- https://docs.killbill.io/latest/plan_alignment.html +- https://docs.killbill.io/latest/overdue.html +- https://docs.killbill.io/latest/consumable_in_arrear.html +- https://docs.killbill.io/latest/ha.html +- https://docs.killbill.io/latest/catalog-examples.html +- https://docs.killbill.io/latest/invoice_examples.html +- https://docs.killbill.io/latest/invoice_templates.html +- https://docs.killbill.io/latest/payment_plugin.html + +## AWS + +- https://docs.killbill.io/latest/aws.html +- https://docs.killbill.io/latest/how-to-set-up-a-single-tier-system.html +- https://docs.killbill.io/latest/how-to-set-up-a-cloud-formation-system.html +- https://docs.killbill.io/latest/aws-container.html +- https://docs.killbill.io/latest/how-to-maintain-a-single-tier-system.html +- https://docs.killbill.io/latest/how-to-maintain-a-multi-tier-system.html +- https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system.html +- https://docs.killbill.io/latest/explanation-https-and-certificates.html +- https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html +- https://docs.killbill.io/latest/using-ses-with-aws.html +- https://docs.killbill.io/latest/events-to-aws-sqs.html +- https://docs.killbill.io/latest/aws-tools.html +- https://docs.killbill.io/latest/metrics-datadog.html +- https://docs.killbill.io/latest/metrics-newrelic.html +- https://docs.killbill.io/latest/metrics-cloudwatch.html +- https://docs.killbill.io/latest/errors-rollbar.html +- https://docs.killbill.io/latest/errors-sentry.html + +## Aviate +- https://docs.killbill.io/latest/what_is_aviate.html +- https://docs.killbill.io/latest/aviate-changelog.html +- https://docs.killbill.io/latest/aviate-deployment-management.html +- https://docs.killbill.io/latest/aviate-getting-started.html +- https://docs.killbill.io/latest/aviate-catalog-guide.html +- https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html +- https://docs.killbill.io/latest/aviate-database-migrations.html +- https://docs.killbill.io/latest/aviate-health.html +- https://docs.killbill.io/latest/aviate-custom-invoice-sequencing.html +- https://docs.killbill.io/latest/aviate-catalog-plugin.html +- https://docs.killbill.io/latest/aviate-metering.html +- https://docs.killbill.io/latest/aviate-wallet.html +- https://docs.killbill.io/latest/aviate-coupons.html +- https://docs.killbill.io/latest/aviate-tax.html +- https://docs.killbill.io/latest/aviate-usage-ai-tutorial.html +- https://docs.killbill.io/latest/aviate-tax-tutorial.html + +## Internal + +- https://docs.killbill.io/latest/internal_design.html +- https://docs.killbill.io/latest/entitlement_subsystem.html +- https://docs.killbill.io/latest/invoice_subsystem.html +- https://docs.killbill.io/latest/development.html \ No newline at end of file diff --git a/latest/skill.md b/latest/skill.md new file mode 100644 index 000000000..4403f03a6 --- /dev/null +++ b/latest/skill.md @@ -0,0 +1,329 @@ +--- +name: Kill Bill +description: Use when working with the Kill Bill open source billing and payments platform. This skill helps with subscriptions, invoices, payments, catalog configuration, plugins, APIs, Kaui administration, tenant configuration, and Java plugin development. +metadata: + version: "1.0" +--- + +# Kill Bill Skill + +## Product summary + +Kill Bill is an open-source subscription billing and payments platform. It handles account management, subscription/entitlement lifecycles, catalog-driven pricing, usage-based billing, invoicing, payments, and overdue/dunning. Kill Bill is highly extensible through plugins and supports multiple payment gateways, tax providers, notification systems, and custom business logic. Kaui is the companion admin UI for Kill Bill. Agents use Kill Bill to create and manage accounts, subscriptions, invoices, payments, and usage data through the REST API, the `killbill-client-java` (or other language) client libraries, or Kaui. + +**Key entry points:** +- REST API: `http://:8080/1.0/kb` (self-hosted; no shared public sandbox URL) +- Admin UI (Kaui): typically deployed at `http://:9090` +- Client libraries: `killbill-client-java`, `killbill-client-python`, `killbill-client-ruby`, `killbill-client-js` +- Plugin manager (KPM): Used to install plugins using `kpm install_java_plugin ` +- Docker: `killbill/killbill` and `killbill/kaui` images + +**Authentication:** HTTP Basic Auth (`-u :`) plus required multi-tenancy headers `X-Killbill-ApiKey` and `X-Killbill-ApiSecret`. Every mutating call should also include `X-Killbill-CreatedBy` (and optionally `X-Killbill-Reason` / `X-Killbill-Comment`). + +**Primary docs:** +- https://docs.killbill.io +- https://apidocs.killbill.io +- https://github.com/killbill + +--- + +## When to use + +Use this skill whenever users ask about: + +- **Kill Bill installation or deployment** - Install Kill Bill in Tomcat, Docker or AWS +- **Account management** - Add new accounts, update billing information, manage addresses, currency, and payment methods +- **Subscription lifecycle** - Create bundles/subscriptions against catalog plans, handle plan changes, cancellations, pause/resume bundles/subscriptions +- **Catalog configuration** - Define products, plans, price lists, phases, and usage tiers in Kill Bill XML or Aviate catalog +- **Invoices and invoice adjustments** - Trigger invoice runs, generate dry-run invoices, adjust/credit invoices, manage invoice items +- **Payments, payment methods and payment retries** - Configure payment plugins (Braintree, Stripe, Adyen, etc.), trigger payments/refunds, manage payment methods, payment retries +- **Usage billing** - Configure tiered usage in the catalog, record usage via the usage API +- **Tags and custom fields** — Attach system tags (e.g. `AUTO_INVOICING_OFF`) to control system behavior, or custom fields to store additional metadata on accounts, subscriptions, and invoices +- **Tenant configuration** — Set up per-tenant catalog, overdue, invoice and payment configuration; manage API keys/secrets and tenant-level feature flags +- **Handling overdue/dunning** — Configure overdue XML rules, enforce overdue logic +- **Querying billing data** — Look up accounts, bundles, subscriptions, invoices, payments, and audit history +- **Administering via Kaui** — Manage tenants, accounts, subscriptions, invoices, payments, users, permissions, and catalogs through the Kaui web UI +- **Extending via plugins** — Write or configure OSGI/Java plugins, notification plugins, payment plugins or other custom plugins +- **REST API usage** — Authenticate, construct multi-tenant headers, and call Kill Bill endpoints directly for custom integrations +- **Java client library** — Generate or use `killbill-client-java` to interact with the API from Java applications instead of raw HTTP calls +- **Troubleshooting Kill Bill behavior** — Diagnose unexpected invoice, payment, or subscription states using audit logs, bus events, and plugin logs + + +--- + +## General guidance + +When answering questions: + +1. Prefer official Kill Bill documentation over assumptions. +2. Mention version-specific behavior when relevant. +3. If multiple approaches exist, recommend the simplest supported approach first. +4. Prefer configuration over custom code when possible. +5. When discussing plugins, clearly distinguish between: + - Kill Bill core + - Kaui + - Payment plugins + - Notification plugins +6. Use official REST API endpoints whenever applicable. +7. For Java development, prefer the supported Kill Bill plugin APIs rather than internal implementation classes. + +--- + + +## Quick reference + +### API authentication + +```bash +# Basic Auth + multi-tenancy headers +curl -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + http://127.0.0.1:8080/1.0/kb/accounts + +# Mutating calls also need CreatedBy +curl -X POST -u admin:password \ + -H "X-Killbill-ApiKey: bob" \ + -H "X-Killbill-ApiSecret: lazar" \ + -H "X-Killbill-CreatedBy: reshma" \ + -H "Content-Type: application/json" \ + -d '{"name": "Acme", "currency": "USD"}' \ + http://127.0.0.1:8080/1.0/kb/accounts +``` + +### Core resources and endpoints + +| Resource | Common operations | +| --- | --- | +| **Accounts** | `POST /1.0/kb/accounts`, `GET /1.0/kb/accounts/{accountId}`, `PUT /1.0/kb/accounts/{accountId}` | +| **Bundles/Subscriptions** | `POST /1.0/kb/subscriptions`, `GET /1.0/kb/subscriptions/{subscriptionId}`, `DELETE /1.0/kb/subscriptions/{subscriptionId}` | +| **Invoices** | `GET /1.0/kb/invoices/{invoiceId}`, `POST /1.0/kb/invoices?dryRun=true`, `POST /1.0/kb/invoices/template` | +| **Payments** | `POST /1.0/kb/accounts/{accountId}/payments`, `GET /1.0/kb/payments/{paymentId}`, `POST /1.0/kb/payments/{paymentId}/refunds` | +| **Payment methods** | `POST /1.0/kb/accounts/{accountId}/paymentMethods`, `GET /1.0/kb/accounts/{accountId}/paymentMethods` | +| **Usage** | `POST /1.0/kb/usages`, `GET /1.0/kb/usages/{subscriptionId}` | +| **Catalog** | `POST /1.0/kb/catalog/xml`, `GET /1.0/kb/catalog` | +| **Tags / Custom fields** | `POST /1.0/kb/accounts/{accountId}/tags`, `POST /1.0/kb/accounts/{accountId}/customFields` | +| **Tenants** | `POST /1.0/kb/tenants`, `POST /1.0/kb/tenants/{tenantId}/uploadPerTenantConfig` | + +### CLI / tooling quick commands + +```bash +# Plugin manager (KPM) +kpm install_java_plugin killbill-stripe --destination=/var/tmp/bundles +kpm diagnostic --killbill-api-credentials=bob lazar --killbill-credentials admin password --account-export=ACCOUNT_ID + +# Docker quick start +docker compose up +``` + +### Kill Bill setup + +Kill Bill itself needs a database (MySQL is the most commonly used/tested, PostgreSQL and MariaDB are also supported) and can be installed several ways depending on environment: a single-tier AWS AMI (quick trial/experimentation), a multi-tier AWS setup or CloudFormation templates (recommended for production), Docker/Docker Compose (local or cloud), or a manual Tomcat installation. + +See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) for the install options and database DDL/setup steps. For the AWS setup options, see the [AWS doc](https://docs.killbill.io/latest/aws). + +--- + +### Kaui setup + +Kaui runs as a separate Rails-based admin app in front of the Kill Bill server; it needs its own database (tables: `kaui_users`, `kaui_tenants`, `kaui_allowed_users`, `kaui_allowed_user_tenants`) and is pointed at the Kill Bill API URL, tenant API key/secret, and admin credentials via environment variables or `kaui.yml`. + +See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) for full install/config steps (WAR setup, database DDL, environment variables). + +--- + +### Environments + +| Environment | Typical use | Notes | +| --- | --- | --- | +| **Local** | Development, quick experimentation, plugin testing | Manual Tomcat install with an H2 or MySQL/PostgreSQL backend | +| **Docker** | Development, faster setup, plugin testing | Uses `killbill/killbill` + `killbill/kaui` images via Docker/Docker Compose, typically with a MySQL/MariaDB container | +| **AWS single-tier** | Trial / experimentation | Everything (Kill Bill + Kaui + DB + nginx) bundled on one EC2 instance via AMI; fastest to spin up, not recommended for production | +| **AWS multi-tier** | Production | AMI-based, components split across tiers; more setup than CloudFormation but more control over the deployment | +| **AWS CloudFormation** | Production | Templated production deployment; less setup than multi-tier, less control in exchange | + + +--- + +## Decision guidance + +### When to use API vs Kaui vs plugin + +| Scenario | Use API | Use Kaui | Use Plugin | +| --- | --- | --- | --- | +| Programmatic integration, backend systems | ✓ | | | +| Manual admin tasks, support investigations | | ✓ | | +| Custom payment gateway integration | | | ✓ | +| Custom tax logic or external tax engine | | | ✓ | +| Scripting and automation | ✓ | | | +| One-off catalog or tenant config changes | ✓ | ✓ | | + +### When to use subscription vs one-off invoice item + +| Use case | Subscription (catalog plan) | One-off invoice item | +| --- | --- | --- | +| Recurring monthly/annual billing | ✓ | | +| Fixed platform fee + usage charges | ✓ | | +| One-time onboarding or implementation fee | | ✓ | +| Ad-hoc credit or adjustment | | ✓ | +| Refund via credit note | | ✓ | + + +### Pricing models + +| Billing mode | Supported pricing models | +| --- | --- | +| **Usage — consumable (in-arrear)** | Tiered blocks, per-unit tiers | +| **Usage — capacity (in-advance)** | Fixed capacity tiers | +| **Recurring** | Fixed price, price list overrides | + +--- + +## Workflow + +### Installing Kill Bill + +1. **Pick a deployment path** — Local Tomcat, Docker/Docker Compose, AWS single-tier, AWS multi-tier, AWS CloudFormation (see Environments table above) +2. **Provision the database** — Create the Kill Bill schema (MySQL recommended; PostgreSQL and MariaDB also supported) and load the Kill Bill DDL. For Docker Compose and the AWS options, this is typically handled by the provided compose file/AMI rather than done manually +3. **Configure the database connection** — Set `killbill.dao.url` / `KILLBILL_DAO_URL` (and user/password) via `killbill.properties`, environment variables, or Docker env vars +4. **Get the Kill Bill server running** — Tomcat installs need the WAR deployed explicitly; Docker uses the prebuilt `killbill/killbill` image directly; AWS AMI/CloudFormation options already bundle the server, so this step is just starting the stack +5. **Install required default bundles/plugins** — `kpm pull_defaultbundles`, plus any payment/tax/notification plugins needed (`kpm install_java_plugin `); not needed if the AMI/image already includes them +6. **Configure payment plugins** — Set plugin-specific properties (API keys, merchant IDs) via per-tenant config or `killbill.properties` +7. **Set up Kaui** — For Tomcat: provision the separate Kaui database and deploy the Kaui WAR. For Docker: run the `killbill/kaui` image. For AWS: already bundled. In all cases, point Kaui at the Kill Bill API URL and admin credentials (see Kaui setup section) +8. **Start the platform** — Bring up Kill Bill, Kaui, and the database (in that dependency order for Docker Compose; already running as one stack for AWS AMI options) +9. **Create a tenant** — Either via Kaui's tenant screen or `POST /1.0/kb/tenants`, capturing the API key/secret +10. **Verify installation** — Confirm Kill Bill responds on `/1.0/kb/accounts`, Kaui logs in and shows the tenant, and a test account/subscription can be created end-to-end + + +### Managing subscriptions + +1. **Create accounts** — `POST /1.0/kb/accounts` with name, currency, and country; verify with `GET` +2. **Create subscriptions** — `POST /1.0/kb/subscriptions` against a valid catalog `planName` (or `productName` + `billingPeriod` + `priceList`), tied to a bundle (`externalKey` optional) +3. **Change plans** — `PUT /1.0/kb/subscriptions/{subscriptionId}` with the new plan; specify `billingPolicy` (immediate vs. end-of-term) and confirm proration behavior against the catalog's change rules +4. **Cancel subscriptions** — `DELETE /1.0/kb/subscriptions/{subscriptionId}` with `entitlementPolicy`/`billingPolicy` (`IMMEDIATE` vs `END_OF_TERM`); note add-ons vs. base plan cancellation rules +5. **Pause or resume billing** — Use entitlement block/unblock APIs (`PUT /1.0/kb/subscriptions/{subscriptionId}/block`) or account-level blocking to suspend billing without cancelling the subscription +6. **Configure billing alignment** — Set `billingAlignment` (account, bundle, or subscription) in the catalog to control how billing dates line up across multiple subscriptions in a bundle +7. **Configure billing rules** — Define plan change rules, cancellation policies, and alignment rules in the catalog XML's `` section + + +### Catalog configuration + +1. **Create products** — Define `` entries in the catalog XML with a name and category (base, add-on, standalone) +2. **Create plans** — Define `` entries linking a product to one or more phases (trial, discount, evergreen) +3. **Create phases** — Configure phase type, duration, and price for each plan phase +4. **Configure price lists** — Group plans into `` blocks to support different pricing tiers for the same products +5. **Configure usage sections** — Add `` blocks (consumable/in-arrear or capacity/in-advance) with tiers and blocks for metered pricing +6. **Configure billing rules** — Set up `` for allowed plan changes, cancellation policies, and billing alignment +7. **Validate XML catalogs** — Check the catalog via the Catalog validation API; test in sandbox first since catalog changes can affect subscriptions on active plans +8. **Upload the catalog** — `POST /1.0/kb/catalog/xml` per tenant, or use the Kaui catalog interface for simpler catalogs built directly in the UI + + +### Payments + +1. **Configure payment gateways** — Install and configure the relevant payment plugin (Stripe, Adyen, PayPal, etc.) via Aviate, KPM, or Kaui, setting gateway credentials in per-tenant or global config +2. **Add payment methods** — `POST /1.0/kb/accounts/{accountId}/paymentMethods`, marking one as default per account +3. **Process payments** — `POST /1.0/kb/accounts/{accountId}/payments` (or let invoicing trigger automatic payment against the default method) +4. **Retry failed payments** — Configure the payment retry rules so failed payments are automatically retried rather than left unresolved +5. **Configure payment control plugins** — Distinguish Payment Plugins (talk to the gateway) from Payment Control Plugins (intercept/authorize/route payment attempts before they reach the gateway, e.g. for fraud checks or custom routing like Evervault Relay) +6. **Troubleshoot payment failures** — Check the payment's transaction history and audit log, gateway-specific error codes, and plugin logs; confirm the payment method and account currency match + + +### Plugin development + +1. **Build Java plugins** — Scaffold from the `killbill-plugin-framework-java`, implementing the relevant plugin API interface (Payment, Invoice, Currency, Notification, etc.) +2. **Implement plugin APIs** — Implement the specific OSGI service interface for your plugin type (e.g. `PaymentPluginApi`, `InvoicePluginApi`) and register it as an OSGI service +3. **Register servlets** — Expose custom HTTP endpoints by creating and registering a servlet +4. **Register listeners** — Create notification plugins by registering listeners that react to events like `INVOICE_CREATION`, `PAYMENT_SUCCESS`, or `OVERDUE_CHANGE` +5. **Register payment APIs** — Create payment plugins by registering classes that implement the `PaymentPluginApi` +6. **Configure OSGI bundles** — Package the plugin as an OSGI bundle with correct manifest metadata; deploy via Aviate, KPM (`kpm install_java_plugin`) or Kaui so it's picked up on Kill Bill startup +7. **Debug plugin issues** — Check plugin-specific logs, confirm correct tenant context resolution on each request (a common source of cross-tenant bugs), and verify the bundle registered successfully via `kpm inspect` + +### REST APIs + +1. **Identify the resource and operation** — Map the request to a Kill Bill resource (account, subscription, invoice, payment, etc.) and HTTP verb (`POST` create, `GET` read, `PUT` update, `DELETE` remove/cancel) +2. **Show the example request** — Include the full `curl` command with method, headers (`X-Killbill-ApiKey`, `X-Killbill-ApiSecret`, `X-Killbill-CreatedBy` for mutations), and JSON body where relevant +3. **Explain required path parameters** — Call out resource IDs (`{accountId}`, `{subscriptionId}`, `{invoiceId}`, etc.) and any required query parameters (e.g. `dryRun`, `targetDate`, `requestedDate`) +4. **Explain the request body** — Walk through required vs. optional fields (e.g. `name`/`currency` for accounts, `planName` vs. `productName`+`billingPeriod`+`priceList` for subscriptions) +5. **Explain the expected response** — Note the success status code (`200`/`201`/`204`), what's returned in the body vs. headers (e.g. new resource ID in the `Location` header), and common error codes (`400` bad request, `401` auth, `404` not found, `500` server/gateway error) +6. **Reference the appropriate API documentation** — Point to the specific endpoint page or the Swagger/REST API reference rather than restating the whole spec + +--- + +## Common terminology + +Understand these common Kill Bill concepts: + +- **Account** — The top-level entity representing a customer; holds currency, billing address, and payment methods +- **Bundle** — A container grouping a base subscription and its add-ons together for billing/entitlement purposes +- **Subscription** — A single instance of a plan a customer is subscribed to, within a bundle +- **Entitlement** — The access/usage rights a customer has, tracked separately from billing; a subscription can lose billing (blocked) while entitlement continues, or vice versa +- **Product** — A sellable offering defined in the catalog (e.g. "Gold") +- **Plan** — A specific pricing/billing configuration for a product (e.g. "gold-monthly") +- **Phase** — A stage within a plan's lifecycle (trial, discount, evergreen), each with its own duration and price +- **Price List** — A named grouping of plans in the catalog, used to offer different pricing tiers for the same products +- **Catalog** — The XML configuration defining products, plans, phases, price lists, and business rules +- **BCD (Bill Cycle Day)** — The day of the month that invoice is created for an account +- **Invoice** — A billing document generated for an account, composed of invoice items +- **Invoice Item** — A single line item on an invoice (recurring charge, usage charge, credit, adjustment, etc.) +- **Payment** — A transaction record representing money collected against one or more invoices +- **Payment Transaction** — A specific step within a payment (authorize, capture, purchase, refund, etc.) +- **Payment Method** — A stored, tokenized way to charge a customer (card, ACH, etc.) via a payment plugin +- **Tenant** — A logically isolated set of data/config within a Kill Bill instance, identified by API key/secret +- **Plugin** — An OSGI extension point for custom payment, invoice, tax, notification, or catalog logic +- **Overdue** — The state machine governing dunning/collection actions when invoices go unpaid +- **Usage Pricing** — Pricing a service or item based on its consumption or usage. +- **Blocking State** — A mechanism to suspend entitlement/billing on an account, bundle, or subscription without cancelling it +- **Custom Field** — Arbitrary key/value metadata attached to a Kill Bill resource like account, bundle, subscription +- **Tag** — A property that can be added to objects (such as accounts, bundles or subscriptions) +- **Audit Log** — The history of who changed a resource, when, and why (via `CreatedBy`/`Reason`/`Comment`) + +--- + +## Common gotchas + +- **Multi-tenancy header mismatch** — Every request needs matching `X-Killbill-ApiKey` / `X-Killbill-ApiSecret` for the tenant; mixing tenants causes 401s or "resource not found" errors even when the ID is valid. +- **Missing `X-Killbill-CreatedBy`** — Mutating calls (POST/PUT/DELETE) fail without this header; it's required for audit logging. +- **Catalog validation errors on upload** — Catalog XML must be validated, otherwise it can break existing subscriptions on active plans. +- **Subscription not invoicing** — Verify the subscription is not blocked by a blocking state or overdue condition, has a valid catalog plan, and the billing/target date has actually passed. +- **Usage events outside the metering period** — Usage recorded with a timestamp outside the current billing period for the subscription won't appear on the current invoice. +- **Plugin tenant resolution issues** — Plugins must correctly resolve tenant context from request headers; missing tenant context causes cross-tenant data leaks or 404s. +- **Kaui pointing at wrong Kill Bill URL** — Kaui must be configured with the correct backend URL. +- **Catalog changes are versioned, not overwritten** — Uploading a new catalog creates a new version rather than mutating history; existing subscriptions keep the pricing/rules from the catalog version they were created under, so historical invoices aren't retroactively affected by later catalog edits. +- **Many configuration changes are tenant-specific** — Catalog, overdue rules, invoice/payment properties, and plugin config can all be set per-tenant via `uploadPerTenantConfig`; a change made under one tenant's API key/secret won't apply to others, and global `killbill.properties` values only act as a fallback when no per-tenant override exists. +- **Plugins execute independently from Kill Bill core** — OSGI plugins run in their own bundle context and can be installed/upgraded/restarted without redeploying the core server; a plugin crashing or misbehaving doesn't necessarily take down core Kill Bill functionality, but a plugin hanging (e.g. a slow payment gateway call) can block the request that invoked it. +- **Payment behavior depends on the configured payment plugin** — Retry logic, supported transaction types (authorize/capture vs. purchase), refund handling, and error code mapping all vary by which payment plugin is installed (Stripe, Adyen, Braintree, etc.); don't assume behavior that's specific to one gateway/plugin generalizes to another. +- **Invoice generation and payment processing are separate operations** — An invoice can be created without a payment being triggered (e.g. `AUTO_PAY_OFF`/`MANUAL_PAY` tags, no default payment method), and conversely a payment can be recorded manually against an invoice outside of the automatic flow; don't assume one implies the other completed. +- **Subscription changes may generate repair adjustments** — Plan changes or cancellations that fall mid-billing-cycle can trigger automatic invoice repair (credits/debits) to reconcile what was already invoiced against the new billing state, governed by the catalog's billing alignment and change rules; check the resulting invoice rather than assuming a clean prorated charge. +- **Always verify whether a feature belongs to Kill Bill core or requires a plugin** — Some capabilities that seem "built in" (tax calculation, certain payment retry strategies, invoice grouping, advanced usage aggregation) actually require a specific plugin to be installed and configured; check the plugin's own docs/config rather than assuming core Kill Bill provides it out of the box. + +--- + +## Verification checklist + +Before submitting work: + +- [ ] **Version-dependent behavior** — Confirm the behavior/endpoint in question is consistent with the Kill Bill version in use, since API and defaults can shift across versions +- [ ] **Required fields** — Account currency is valid, subscription plan/price list are set explicitly +- [ ] **Payment method** — Account has a default payment method if automatic charging is expected +- [ ] **Tags** — `AUTO_INVOICING_OFF`/`AUTO_INVOICING_DRAFT` tags are added/removed intentionally, not left over from testing +- [ ] **Response validation** — Check HTTP status (2xx success, 4xx client error, 5xx server error) and inspect audit logs for unexpected state + +--- + +## Resources + +**Comprehensive navigation:** https://docs.killbill.io + +**Critical documentation pages:** +- [Getting started](https://docs.killbill.io/latest/getting_started) +- [Subscription and entitlement overview](https://docs.killbill.io/latest/userguide_subscription) +- [Plugin development](https://docs.killbill.io/latest/plugin_development) +- [Kaui admin UI](https://docs.killbill.io/latest/userguide_kaui) +- [Rest API Reference](https://apidocs.killbill.io) +- [Source Code](https://github.com/killbill) +- [Community](https://groups.google.com/g/killbilling-users) +- [Documentation Index](https://docs.killbill.io/llms.txt) + +--- + +> For additional documentation and navigation, see: https://docs.killbill.io From 9ff6b0e30df714657f2c48f696bb710d657e877c Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Mon, 20 Jul 2026 12:35:04 +0530 Subject: [PATCH 2/4] changes as per review comments --- latest/llms.txt | 200 ++++++++++++++++++++++++------------------------ latest/skill.md | 19 +++-- 2 files changed, 109 insertions(+), 110 deletions(-) diff --git a/latest/llms.txt b/latest/llms.txt index c452a662d..5d2f67023 100644 --- a/latest/llms.txt +++ b/latest/llms.txt @@ -4,119 +4,119 @@ ## Understand Kill Bill and Getting Started with Kill Bill -- https://docs.killbill.io/latest/what_is_kill_bill.html -- https://docs.killbill.io/latest/features.html -- https://docs.killbill.io/latest/premium_features.html -- https://docs.killbill.io/latest/demo.html -- https://docs.killbill.io/latest/faq.html -- https://docs.killbill.io/latest/Kill-Bill-Glossary.html -- https://docs.killbill.io/latest/getting_started.html -- https://docs.killbill.io/latest/killbill-changelog.html -- https://github.com/killbill/killbill/releases -- https://github.com/killbill/killbill-admin-ui-standalone/releases -- https://docs.killbill.io/latest/quick_start_with_kaui.html -- https://docs.killbill.io/latest/quick_start_with_kb_api.html -- https://docs.killbill.io/latest/stripe_plugin.html -- https://docs.killbill.io/latest/userguide_subscription.html -- https://docs.killbill.io/latest/userguide_payment.html -- https://docs.killbill.io/latest/internationalization.html -- https://docs.killbill.io/latest/migration_guide.html +- https://docs.killbill.io/latest/what_is_kill_bill.html — High-level overview of what Kill Bill is and the problems it solves. +- https://docs.killbill.io/latest/features.html — Summary of Kill Bill's core feature set. +- https://docs.killbill.io/latest/premium_features.html — Overview of premium (paid/enterprise) features on top of open-source Kill Bill. +- https://docs.killbill.io/latest/demo.html — How to spin up and explore the Kill Bill demo environment. +- https://docs.killbill.io/latest/faq.html — Frequently asked questions about Kill Bill. +- https://docs.killbill.io/latest/Kill-Bill-Glossary.html — Glossary of Kill Bill terms and concepts. +- https://docs.killbill.io/latest/getting_started.html — Entry-point guide for installing Kill Bill for the first time. +- https://docs.killbill.io/latest/killbill-changelog.html — Changelog of releases and notable changes to Kill Bill/Kaui. +- https://github.com/killbill/killbill/releases — GitHub releases page for Kill Bill core. +- https://github.com/killbill/killbill-admin-ui-standalone/releases — GitHub releases page for Kaui (the admin UI). +- https://docs.killbill.io/latest/quick_start_with_kaui.html — Quick-start guide to using Kaui. +- https://docs.killbill.io/latest/quick_start_with_kb_api.html — Quick-start guide to using the Kill Bill REST API directly. +- https://docs.killbill.io/latest/stripe_plugin.html — Kill Bill/Stripe Integration demo. +- https://docs.killbill.io/latest/userguide_subscription.html — User guide covering catalog/subscription/entitlement/invoice/payment concepts and workflows. +- https://docs.killbill.io/latest/userguide_payment.html — User guide covering the payment subsystem and workflows. +- https://docs.killbill.io/latest/internationalization.html — Overview of Kill Bill's internationalization/localization support (currencies, languages, time zones). +- https://docs.killbill.io/latest/migration_guide.html — Guide for migrating data/systems into Kill Bill. +## Deploy, Operate, and Integrate -## Deploy, Operate and Integrate - -- https://docs.killbill.io/latest/userguide_configuration.html -- https://docs.killbill.io/latest/userguide_deployment.html -- https://docs.killbill.io/latest/deploy_to_kubernetes.html -- https://docs.killbill.io/latest/how-to-upgrade-the-database.html -- https://docs.killbill.io/latest/PostgreSQL.html -- https://docs.killbill.io/latest/user_management.html -- https://docs.killbill.io/latest/how-to-use-kpm-diagnostic.html -- https://apidocs.killbill.io/ -- https://docs.killbill.io/latest/swagger_documentation.html -- https://docs.killbill.io/latest/postman.html -- https://docs.killbill.io/latest/push_notifications.html -- https://docs.killbill.io/latest/kill_bill_events.html -- https://docs.killbill.io/latest/java_client.html -- https://github.com/killbill/killbill-client-ruby -- https://github.com/killbill/killbill-client-php -- https://github.com/killbill/killbill-client-js -- https://github.com/killbill/killbill-client-python -- https://github.com/killbill/kbcli -- https://docs.killbill.io/latest/debugging.html +- https://docs.killbill.io/latest/userguide_configuration.html — Reference for configuring Kill Bill (system properties, per-tenant config). +- https://docs.killbill.io/latest/userguide_deployment.html — General guide to deploying Kill Bill in production. +- https://docs.killbill.io/latest/deploy_to_kubernetes.html — Guide to deploying Kill Bill on Kubernetes. +- https://docs.killbill.io/latest/how-to-upgrade-the-database.html — Steps for running database schema upgrades between versions. +- https://docs.killbill.io/latest/PostgreSQL.html — Notes on running Kill Bill with PostgreSQL. +- https://docs.killbill.io/latest/user_management.html — Guide to managing admin users, roles, and permissions. +- https://docs.killbill.io/latest/how-to-use-kpm-diagnostic.html — How to use KPM's diagnostic tooling to troubleshoot a deployment. +- https://apidocs.killbill.io/ — Full REST API reference documentation. +- https://docs.killbill.io/latest/swagger_documentation.html — Guide to the Swagger/OpenAPI spec for the Kill Bill API. +- https://docs.killbill.io/latest/postman.html — Guide to using the Postman collection for exploring the API. +- https://docs.killbill.io/latest/push_notifications.html — Guide to configuring push notifications for Kill Bill events. +- https://docs.killbill.io/latest/kill_bill_events.html — Reference for the Kill Bill event types. +- https://docs.killbill.io/latest/java_client.html — Guide to using the Java client library. +- https://github.com/killbill/killbill-client-ruby — Ruby client library for the Kill Bill API. +- https://github.com/killbill/killbill-client-php — PHP client library for the Kill Bill API. +- https://github.com/killbill/killbill-client-js — JavaScript client library for the Kill Bill API. +- https://github.com/killbill/killbill-client-python — Python client library for the Kill Bill API. +- https://github.com/killbill/kbcli — Command-line client (kbcli) for interacting with Kill Bill. +- https://docs.killbill.io/latest/debugging.html — Tips and tools for debugging a running Kill Bill instance. ## Plugins -- https://docs.killbill.io/latest/plugin_introduction.html -- https://docs.killbill.io/latest/plugin_development.html -- https://docs.killbill.io/latest/plugin_installation.html -- https://docs.killbill.io/latest/plugin_management.html -- https://docs.killbill.io/latest/plugin_use_cases.html -- https://docs.killbill.io/latest/email-notification-plugin.html -- https://docs.killbill.io/latest/userguide_analytics.html -- https://docs.killbill.io/latest/avatax-plugin.html -- https://docs.killbill.io/latest/braintree-plugin.html -- https://docs.killbill.io/latest/notification_plugin.html -- https://docs.killbill.io/latest/payment_plugin.html -- https://docs.killbill.io/latest/payment_control_plugin.html -- https://docs.killbill.io/latest/usage_plugin.html -- https://docs.killbill.io/latest/invoice_plugin.html -- https://docs.killbill.io/latest/catalog_plugin.html -- https://docs.killbill.io/latest/entitlement_plugin.html -- https://docs.killbill.io/latest/custom-email-invoice-formatter.html +- https://docs.killbill.io/latest/plugin_introduction.html — Introduction to the Kill Bill plugin architecture. +- https://docs.killbill.io/latest/plugin_development.html — Guide to developing a custom Kill Bill plugin. +- https://docs.killbill.io/latest/plugin_installation.html — Guide to install and register a plugin. +- https://docs.killbill.io/latest/plugin_management.html — How to manage (install/uninstall/enable/disable) plugins via API. +- https://docs.killbill.io/latest/plugin_use_cases.html — Overview of specific plugin use cases. +- https://docs.killbill.io/latest/email-notification-plugin.html — Setup and usage guide for the email notification plugin. +- https://docs.killbill.io/latest/userguide_analytics.html — Setup and usage guide for the Analytics plugin. +- https://docs.killbill.io/latest/avatax-plugin.html — Setup and usage guide for the Avalara AvaTax tax plugin. +- https://docs.killbill.io/latest/braintree-plugin.html — Setup and usage guide for the Braintree payment plugin. +- https://docs.killbill.io/latest/notification_plugin.html — Reference for building/using generic notification plugins. +- https://docs.killbill.io/latest/payment_plugin.html — Reference for building/using a payment plugin. +- https://docs.killbill.io/latest/payment_control_plugin.html — Reference for payment control plugins (routing/retry logic). +- https://docs.killbill.io/latest/usage_plugin.html — Reference for usage plugins used in metered/consumable billing. +- https://docs.killbill.io/latest/invoice_plugin.html — Reference for invoice plugins that customize invoice generation. +- https://docs.killbill.io/latest/catalog_plugin.html — Reference for catalog plugins that serve dynamic catalogs. +- https://docs.killbill.io/latest/entitlement_plugin.html — Reference for entitlement plugins customizing subscription behavior. +- https://docs.killbill.io/latest/custom-email-invoice-formatter.html — Guide to customizing email invoices. ## Tutorials and Examples -- https://docs.killbill.io/latest/plan_alignment.html -- https://docs.killbill.io/latest/overdue.html -- https://docs.killbill.io/latest/consumable_in_arrear.html -- https://docs.killbill.io/latest/ha.html -- https://docs.killbill.io/latest/catalog-examples.html -- https://docs.killbill.io/latest/invoice_examples.html -- https://docs.killbill.io/latest/invoice_templates.html -- https://docs.killbill.io/latest/payment_plugin.html +- https://docs.killbill.io/latest/plan_alignment.html — Explanation of plan/phase alignment rules during subscription changes. +- https://docs.killbill.io/latest/overdue.html — Guide to configuring Kill Bill's payment retry system and overdue states. +- https://docs.killbill.io/latest/consumable_in_arrear.html — Tutorial on setting up consumable-in-arrear (usage-based) billing. +- https://docs.killbill.io/latest/ha.html — Guide to configuring Kill Bill for high availability. +- https://docs.killbill.io/latest/catalog-examples.html — Walkthroughs of sample catalog XMLs showing how billing modes, plan phases, multi-plan/add-on setups, billing/subscription alignment rules, usage billing, and catalog versioning each affect resulting invoices. +- https://docs.killbill.io/latest/invoice_examples.html — Walks through how an invoice's charged amount and balance are computed across scenarios like recurring billing, account/invoice credits, item adjustments, and refunds. +- https://docs.killbill.io/latest/invoice_templates.html — Guide to customizing invoice templates. ## AWS -- https://docs.killbill.io/latest/aws.html -- https://docs.killbill.io/latest/how-to-set-up-a-single-tier-system.html -- https://docs.killbill.io/latest/how-to-set-up-a-cloud-formation-system.html -- https://docs.killbill.io/latest/aws-container.html -- https://docs.killbill.io/latest/how-to-maintain-a-single-tier-system.html -- https://docs.killbill.io/latest/how-to-maintain-a-multi-tier-system.html -- https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system.html -- https://docs.killbill.io/latest/explanation-https-and-certificates.html -- https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html -- https://docs.killbill.io/latest/using-ses-with-aws.html -- https://docs.killbill.io/latest/events-to-aws-sqs.html -- https://docs.killbill.io/latest/aws-tools.html -- https://docs.killbill.io/latest/metrics-datadog.html -- https://docs.killbill.io/latest/metrics-newrelic.html -- https://docs.killbill.io/latest/metrics-cloudwatch.html -- https://docs.killbill.io/latest/errors-rollbar.html -- https://docs.killbill.io/latest/errors-sentry.html +- https://docs.killbill.io/latest/aws.html — Overview of options for running Kill Bill on AWS. +- https://docs.killbill.io/latest/how-to-set-up-a-single-tier-system.html — Guide to setting up a single-tier AWS deployment. +- https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system.html - Guide to setting up a multi-tier AWS deployment. +- https://docs.killbill.io/latest/how-to-set-up-a-cloud-formation-system.html — Guide to deploying Kill Bill on AWS via CloudFormation. +- https://docs.killbill.io/latest/aws-container.html — Guide to running the Kill Bill container image on AWS. +- https://docs.killbill.io/latest/how-to-maintain-a-single-tier-system.html — Ongoing maintenance guide for a single-tier AWS deployment. +- https://docs.killbill.io/latest/how-to-maintain-a-multi-tier-system.html — Ongoing maintenance guide for a multi-tier AWS deployment. +- https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system.html — Ongoing maintenance guide for a CloudFormation-based deployment. +- https://docs.killbill.io/latest/explanation-https-and-certificates.html — Explanation of HTTPS/TLS certificate setup for Kill Bill. +- https://docs.killbill.io/latest/how-to-add-a-certificate-using-ACM.html — Guide to attaching an AWS ACM certificate to a deployment. +- https://docs.killbill.io/latest/using-ses-with-aws.html — Guide to configuring AWS SES for outbound email. +- https://docs.killbill.io/latest/events-to-aws-sqs.html — Guide to forwarding Kill Bill events to AWS SQS. +- https://docs.killbill.io/latest/aws-tools.html — Overview of supporting AWS tooling used with Kill Bill. +- https://docs.killbill.io/latest/metrics-datadog.html — Guide to sending Kill Bill metrics to Datadog. +- https://docs.killbill.io/latest/metrics-newrelic.html — Guide to sending Kill Bill metrics to New Relic. +- https://docs.killbill.io/latest/metrics-cloudwatch.html — Guide to sending Kill Bill metrics to AWS CloudWatch. +- https://docs.killbill.io/latest/errors-rollbar.html — Guide to forwarding Kill Bill errors to Rollbar. +- https://docs.killbill.io/latest/errors-sentry.html — Guide to forwarding Kill Bill errors to Sentry. ## Aviate -- https://docs.killbill.io/latest/what_is_aviate.html -- https://docs.killbill.io/latest/aviate-changelog.html -- https://docs.killbill.io/latest/aviate-deployment-management.html -- https://docs.killbill.io/latest/aviate-getting-started.html -- https://docs.killbill.io/latest/aviate-catalog-guide.html -- https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html -- https://docs.killbill.io/latest/aviate-database-migrations.html -- https://docs.killbill.io/latest/aviate-health.html -- https://docs.killbill.io/latest/aviate-custom-invoice-sequencing.html -- https://docs.killbill.io/latest/aviate-catalog-plugin.html -- https://docs.killbill.io/latest/aviate-metering.html -- https://docs.killbill.io/latest/aviate-wallet.html -- https://docs.killbill.io/latest/aviate-coupons.html -- https://docs.killbill.io/latest/aviate-tax.html -- https://docs.killbill.io/latest/aviate-usage-ai-tutorial.html -- https://docs.killbill.io/latest/aviate-tax-tutorial.html + +- https://docs.killbill.io/latest/what_is_aviate.html — Overview of Aviate and what it adds on top of Kill Bill. +- https://docs.killbill.io/latest/aviate-changelog.html — Changelog of Aviate UI and Aviate plugin. +- https://docs.killbill.io/latest/aviate-deployment-management.html — Guide to managing (adding/editing/deleting) Kill Bill deployments in Aviate UI. +- https://docs.killbill.io/latest/aviate-getting-started.html — Getting-started guide for Aviate. +- https://docs.killbill.io/latest/aviate-catalog-guide.html — Guide to building and managing catalogs in Aviate. +- https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html — Step-by-step install guide for the Aviate plugin. +- https://docs.killbill.io/latest/aviate-database-migrations.html — Guide to running Aviate's database migrations. +- https://docs.killbill.io/latest/aviate-health.html — Guide to Aviate's health-check endpoints/monitoring. +- https://docs.killbill.io/latest/aviate-custom-invoice-sequencing.html — Guide to configuring custom invoice numbering/sequencing in Aviate. +- https://docs.killbill.io/latest/aviate-catalog-plugin.html — Guide to the Aviate catalog plugin, which lets you manage plans/products/pricelists individually via API (instead of whole XML catalog versions). +- https://docs.killbill.io/latest/aviate-metering.html — Guide to creating billing meters and submitting usage events via Aviate. +- https://docs.killbill.io/latest/aviate-wallet.html — Guide to Aviate's prepaid credit wallet per account. +- https://docs.killbill.io/latest/aviate-coupons.html — Guide to configuring and applying coupons in Aviate. +- https://docs.killbill.io/latest/aviate-tax.html — Guide to tax configuration and calculation in Aviate. +- https://docs.killbill.io/latest/aviate-usage-ai-tutorial.html — End-to-end tutorial simulating AI token billing: setting up a billing meter and usage-based catalog plan, creating a wallet with paid credits and auto top-off, recording usage events, and invoicing. +- https://docs.killbill.io/latest/aviate-tax-tutorial.html — Step-by-step tutorial for setting up tax in Aviate UI. ## Internal -- https://docs.killbill.io/latest/internal_design.html -- https://docs.killbill.io/latest/entitlement_subsystem.html -- https://docs.killbill.io/latest/invoice_subsystem.html -- https://docs.killbill.io/latest/development.html \ No newline at end of file +- https://docs.killbill.io/latest/internal_design.html — Overview of Kill Bill's internal architecture and design principles. +- https://docs.killbill.io/latest/entitlement_subsystem.html — Deep dive into the entitlement/subscription subsystem internals. +- https://docs.killbill.io/latest/invoice_subsystem.html — Deep dive into the invoicing subsystem internals. +- https://docs.killbill.io/latest/development.html — Guide for contributors building/developing Kill Bill itself. \ No newline at end of file diff --git a/latest/skill.md b/latest/skill.md index 4403f03a6..51b418fea 100644 --- a/latest/skill.md +++ b/latest/skill.md @@ -23,7 +23,6 @@ Kill Bill is an open-source subscription billing and payments platform. It handl **Primary docs:** - https://docs.killbill.io - https://apidocs.killbill.io -- https://github.com/killbill --- @@ -64,6 +63,8 @@ When answering questions: - Kaui - Payment plugins - Notification plugins + - Open source plugins (Like Stripe, Adyen, Braintree, etc.) + - Private/Custom plugins 6. Use official REST API endpoints whenever applicable. 7. For Java development, prefer the supported Kill Bill plugin APIs rather than internal implementation classes. @@ -108,8 +109,10 @@ curl -X POST -u admin:password \ ### CLI / tooling quick commands ```bash -# Plugin manager (KPM) +# Plugin installation via KPM kpm install_java_plugin killbill-stripe --destination=/var/tmp/bundles + +# Generating diagnostic file via kpm kpm diagnostic --killbill-api-credentials=bob lazar --killbill-credentials admin password --account-export=ACCOUNT_ID # Docker quick start @@ -118,16 +121,13 @@ docker compose up ### Kill Bill setup -Kill Bill itself needs a database (MySQL is the most commonly used/tested, PostgreSQL and MariaDB are also supported) and can be installed several ways depending on environment: a single-tier AWS AMI (quick trial/experimentation), a multi-tier AWS setup or CloudFormation templates (recommended for production), Docker/Docker Compose (local or cloud), or a manual Tomcat installation. - -See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) for the install options and database DDL/setup steps. For the AWS setup options, see the [AWS doc](https://docs.killbill.io/latest/aws). - +Kill Bill can be installed in several ways depending on the environment: a single-tier AWS AMI (quick trial/experimentation), a multi-tier AWS setup or CloudFormation templates (recommended for production), Docker/Docker Compose (local or cloud), or a manual Tomcat installation. See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) for the install options and database DDL/setup steps. For the AWS setup options, see the [AWS doc](https://docs.killbill.io/latest/aws). +Kill Bill needs a database, MySQL is the most commonly used/tested, PostgreSQL and MariaDB are also supported. For Docker Compose and the AWS options, this is typically handled by the provided compose file/AMI rather than done manually. For Tomcat installs, the Kill Bill schema needs to be created manually using [this DDL](https://docs.killbill.io/latest/ddl.sql) for the schema creation and table setup. --- ### Kaui setup -Kaui runs as a separate Rails-based admin app in front of the Kill Bill server; it needs its own database (tables: `kaui_users`, `kaui_tenants`, `kaui_allowed_users`, `kaui_allowed_user_tenants`) and is pointed at the Kill Bill API URL, tenant API key/secret, and admin credentials via environment variables or `kaui.yml`. - +Kaui runs as a separate Rails-based admin app in front of the Kill Bill server. It needs its own database tables. For Docker Compose and the AWS options, this is typically handled by the provided compose file/AMI. In case of manul Tomcat installation, it can be created using [this DDL](https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql) . Kaui also needs to be configured to point to the Kill Bill API URL, and the Kaui database. See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) for full install/config steps (WAR setup, database DDL, environment variables). --- @@ -262,7 +262,7 @@ Understand these common Kill Bill concepts: - **Phase** — A stage within a plan's lifecycle (trial, discount, evergreen), each with its own duration and price - **Price List** — A named grouping of plans in the catalog, used to offer different pricing tiers for the same products - **Catalog** — The XML configuration defining products, plans, phases, price lists, and business rules -- **BCD (Bill Cycle Day)** — The day of the month that invoice is created for an account +- **BCD (Bill Cycle Day)** — The day of the month that invoice is created for an account. This is applicable only for month based billing periods (like `MONTHLY`, `QAUATERLY`, `ANNUAL`, etc.). It can be configured at the account level or overridden at the subscription level. - **Invoice** — A billing document generated for an account, composed of invoice items - **Invoice Item** — A single line item on an invoice (recurring charge, usage charge, credit, adjustment, etc.) - **Payment** — A transaction record representing money collected against one or more invoices @@ -326,4 +326,3 @@ Before submitting work: --- -> For additional documentation and navigation, see: https://docs.killbill.io From 58105cd646901ff20abb38b5e90cad1229fa1840 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Tue, 21 Jul 2026 10:39:23 +0530 Subject: [PATCH 3/4] example scripts --- latest/skill.md | 368 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 368 insertions(+) diff --git a/latest/skill.md b/latest/skill.md index 51b418fea..d48388820 100644 --- a/latest/skill.md +++ b/latest/skill.md @@ -145,6 +145,374 @@ See the [Getting Started guide](https://docs.killbill.io/latest/getting_started) --- +## Example scripts + +Example end-to-end script(s) an agent can adapt and run, parameterized so the same script works across local, Docker, or deployed environments. Intended as a starting point for quick demos/scaffolding — review and harden (secret handling, idempotency, error recovery) before using in any shared or production environment. + +### End-to-end: tenant → account → catalog plan → subscription → invoice check + +**Parameters:** +- **Env** + - `KB_URL` — Kill Bill base URL (e.g. `http://127.0.0.1:8080`) + - `KB_USER` / `PASSWORD` — admin credentials for Basic Auth + - `API_KEY` / `API_SECRET` — tenant credentials (chosen by the caller, not pre-existing) +- **Plan** + - `PRODUCT_NAME` — product name (e.g. `Standard`) + - `PLAN_NAME` — plan name (e.g. `gold-monthly`) + - `CURRENCY` — billing currency (e.g. `USD`) + - `PRICE` — recurring price (e.g. `10.00`) + - `BILLING_PERIOD` — billing frequency (e.g. `MONTHLY`) + +```bash +#!/usr/bin/env bash +set -euo pipefail + +# --- Params --- +KB_URL="${KB_URL:-http://127.0.0.1:8080}" +KB_USER="${KB_USER:-admin}" +PASSWORD="${PASSWORD:-password}" +API_KEY="${API_KEY:-demo-tenant}" +API_SECRET="${API_SECRET:-demo-secret}" + +PLAN_NAME="${PLAN_NAME:-standard-monthly}" +PRODUCT_NAME="${PRODUCT_NAME:-Standard}" +PRICE="${PRICE:-10.00}" +CURRENCY="${CURRENCY:-USD}" +BILLING_PERIOD="${BILLING_PERIOD:-MONTHLY}" + +AUTH=(-u "${KB_USER}:${PASSWORD}") +TENANT_HEADERS=(-H "X-Killbill-ApiKey: ${API_KEY}" -H "X-Killbill-ApiSecret: ${API_SECRET}") +CREATED_BY=(-H "X-Killbill-CreatedBy: setup-script") + +echo "=== Step 1: Create tenant (${API_KEY}) ===" +set +e +STATUS=$(curl -s -o /tmp/tenant_response.json -w "%{http_code}" -X POST "${AUTH[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"apiKey\": \"${API_KEY}\", \"apiSecret\": \"${API_SECRET}\"}" \ + "${KB_URL}/1.0/kb/tenants") +CURL_EXIT=$? +set -e +if [[ "${CURL_EXIT}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${CURL_EXIT}). Is Kill Bill running and reachable at ${KB_URL}?" + exit 1 +fi +echo "HTTP status: ${STATUS}" +cat /tmp/tenant_response.json +echo +if [[ "${STATUS}" != "201" ]]; then + echo "WARNING: expected 201 Created, got ${STATUS}. Response body above may explain why (e.g. tenant already exists)." +fi + +echo +echo "=== Step 2: Create simple plan (${PLAN_NAME}) ===" +set +e +STATUS=$(curl -s -o /tmp/catalog_response.json -w "%{http_code}" -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -d "{\"planId\": \"${PLAN_NAME}\", \"productName\": \"${PRODUCT_NAME}\", \"productCategory\": \"BASE\", \"currency\": \"${CURRENCY}\", \"amount\": ${PRICE}, \"billingPeriod\": \"${BILLING_PERIOD}\", \"trialLength\": 0, \"trialTimeUnit\": \"UNLIMITED\"}" \ + "${KB_URL}/1.0/kb/catalog/simplePlan") +CURL_EXIT=$? +set -e +if [[ "${CURL_EXIT}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${CURL_EXIT})." + exit 1 +fi +echo "HTTP status: ${STATUS}" +cat /tmp/catalog_response.json +echo +if [[ "${STATUS}" != "201" ]]; then + echo "WARNING: expected 201 Created, got ${STATUS}. Check the response above." +fi + +echo +echo "=== Step 3: Create account ===" +set +e +STATUS=$(curl -s -D /tmp/account_headers.txt -o /tmp/account_response.json -w "%{http_code}" -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"name\": \"Demo Customer\", \"currency\": \"${CURRENCY}\"}" \ + "${KB_URL}/1.0/kb/accounts") +CURL_EXIT=$? +set -e +if [[ "${CURL_EXIT}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${CURL_EXIT})." + exit 1 +fi +echo "HTTP status: ${STATUS}" +cat /tmp/account_response.json +echo +ACCOUNT_ID=$(grep -i "^Location:" /tmp/account_headers.txt | sed -E 's#.*/accounts/([a-f0-9-]+).*#\1#i' | tr -d '\r') +if [[ -z "${ACCOUNT_ID}" ]]; then + echo "ERROR: could not extract accountId. Aborting." + exit 1 +fi +echo "Created account: ${ACCOUNT_ID}" + +echo +echo "=== Step 4: Create subscription (plan: ${PLAN_NAME}) ===" +set +e +STATUS=$(curl -s -o /tmp/sub_response.json -w "%{http_code}" -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"accountId\": \"${ACCOUNT_ID}\", \"planName\": \"${PLAN_NAME}\"}" \ + "${KB_URL}/1.0/kb/subscriptions") +CURL_EXIT=$? +set -e +if [[ "${CURL_EXIT}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${CURL_EXIT})." + exit 1 +fi +echo "HTTP status: ${STATUS}" +cat /tmp/sub_response.json +echo +if [[ "${STATUS}" != "201" ]]; then + echo "WARNING: expected 201 Created, got ${STATUS}. Subscription may not have been created." +fi + +echo +echo "=== Step 5: Check invoices for account ${ACCOUNT_ID} ===" +sleep 2 +curl -s "${AUTH[@]}" "${TENANT_HEADERS[@]}" \ + "${KB_URL}/1.0/kb/accounts/${ACCOUNT_ID}/invoices" | jq . + +echo +echo "=== Done ===" +``` + +### Usage billing: tenant → usage-based catalog plan → account → subscription → record usage → dry-run invoice + +**Parameters:** +- **Env** + - `KB_URL` — Kill Bill base URL (e.g. `http://127.0.0.1:8080`) + - `KB_USER` / `PASSWORD` — admin credentials for Basic Auth + - `API_KEY` / `API_SECRET` — tenant credentials (chosen by the caller, not pre-existing) +- **Plan** + - `PRODUCT_NAME` — product name (e.g. `ApiAccess`) + - `PLAN_NAME` — plan name (e.g. `api-monthly`) + - `CURRENCY` — billing currency (e.g. `USD`) + - `BASE_PRICE` — flat recurring price charged regardless of usage (e.g. `20.00`) + - `BILLING_PERIOD` — billing frequency (e.g. `MONTHLY`) +- **Usage** + - `UNIT_NAME` — the metered unit type + +````bash +#!/usr/bin/env bash +set -euo pipefail + +# --- Params: Env --- +KB_URL="${KB_URL:-http://127.0.0.1:8080}" +KB_USER="${KB_USER:-admin}" +PASSWORD="${PASSWORD:-password}" +API_KEY="${API_KEY:-demo-usage-tenant}" +API_SECRET="${API_SECRET:-demo-secret}" + +# --- Params: Plan --- +PLAN_NAME="${PLAN_NAME:-api-monthly}" +PRODUCT_NAME="${PRODUCT_NAME:-ApiAccess}" +CURRENCY="${CURRENCY:-USD}" +BASE_PRICE="${BASE_PRICE:-20.00}" +BILLING_PERIOD="${BILLING_PERIOD:-MONTHLY}" + +# --- Params: Usage --- +UNIT_NAME="${UNIT_NAME:-api-calls}" +TIER1_MAX="${TIER1_MAX:-1000}" # units included in the cheaper tier +TIER1_PRICE="${TIER1_PRICE:-0.01}" # price per unit up to TIER1_MAX +TIER2_PRICE="${TIER2_PRICE:-0.005}" # price per unit beyond TIER1_MAX + +AUTH=(-u "${KB_USER}:${PASSWORD}") +TENANT_HEADERS=(-H "X-Killbill-ApiKey: ${API_KEY}" -H "X-Killbill-ApiSecret: ${API_SECRET}") +CREATED_BY=(-H "X-Killbill-CreatedBy: usage-demo-script") + +# Helper: run a curl call, capture status + body, warn if not the expected code +run_curl() { + local expected_status="$1"; shift + local out_file="$1"; shift + set +e + local status + status=$(curl -s -o "${out_file}" -w "%{http_code}" "$@") + local exit_code=$? + set -e + if [[ "${exit_code}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${exit_code}). Is Kill Bill running and reachable at ${KB_URL}?" + exit 1 + fi + echo "HTTP status: ${status}" + cat "${out_file}" + echo + if [[ "${status}" != "${expected_status}" ]]; then + echo "WARNING: expected ${expected_status}, got ${status}. See response above." + fi +} + +echo "=== Step 1: Create tenant (${API_KEY}) ===" +run_curl 201 /tmp/tenant_response.json \ + -X POST "${AUTH[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"apiKey\": \"${API_KEY}\", \"apiSecret\": \"${API_SECRET}\"}" \ + "${KB_URL}/1.0/kb/tenants" + +echo +echo "=== Step 2: Upload catalog with usage plan (${PLAN_NAME}, unit: ${UNIT_NAME}) ===" +cat > /tmp/usage_catalog.xml < + + 2026-01-01T00:00:00+00:00 + UsageDemoCatalog + IN_ARREAR + + ${CURRENCY} + + + + + + + BASE + + + + + + END_OF_TERM + + + + + END_OF_TERM + + + + + + ${PRODUCT_NAME} + + + + UNLIMITED + + + ${BILLING_PERIOD} + + + ${CURRENCY} + ${BASE_PRICE} + + + + + + ${BILLING_PERIOD} + + + + + ${UNIT_NAME} + 1 + + + ${CURRENCY} + ${TIER1_PRICE} + + + ${TIER1_MAX} + + + + + + + ${UNIT_NAME} + 1 + + + ${CURRENCY} + ${TIER2_PRICE} + + + 10000000 + + + + + + + + + + + + + ${PLAN_NAME} + + + + +XML_EOF + +run_curl 201 /tmp/catalog_response.json \ + -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: text/xml" \ + --data-binary @/tmp/usage_catalog.xml \ + "${KB_URL}/1.0/kb/catalog/xml" + +echo +echo "=== Step 3: Create account ===" +STATUS_TMP=/tmp/account_headers.txt +set +e +STATUS=$(curl -s -D "${STATUS_TMP}" -o /tmp/account_response.json -w "%{http_code}" \ + -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"name\": \"Usage Demo Customer\", \"currency\": \"${CURRENCY}\"}" \ + "${KB_URL}/1.0/kb/accounts") +CURL_EXIT=$? +set -e +if [[ "${CURL_EXIT}" -ne 0 ]]; then + echo "ERROR: curl failed to connect (exit code ${CURL_EXIT})." + exit 1 +fi +echo "HTTP status: ${STATUS}" +cat /tmp/account_response.json +echo +ACCOUNT_ID=$(grep -i "^Location:" "${STATUS_TMP}" | sed -E 's#.*/accounts/([a-f0-9-]+).*#\1#i' | tr -d '\r') +if [[ -z "${ACCOUNT_ID}" ]]; then + echo "ERROR: could not extract accountId. Aborting." + exit 1 +fi +echo "Created account: ${ACCOUNT_ID}" + +echo +echo "=== Step 4: Create subscription (plan: ${PLAN_NAME}) ===" +run_curl 201 /tmp/sub_headers.json \ + -D /tmp/sub_headers.txt \ + -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"accountId\": \"${ACCOUNT_ID}\", \"planName\": \"${PLAN_NAME}\"}" \ + "${KB_URL}/1.0/kb/subscriptions" +SUBSCRIPTION_ID=$(grep -i "^Location:" /tmp/sub_headers.txt | sed -E 's#.*/subscriptions/([a-f0-9-]+).*#\1#i' | tr -d '\r') +echo "Created subscription: ${SUBSCRIPTION_ID}" + +echo +echo "=== Step 5: Record usage events (unit: ${UNIT_NAME}) ===" +USAGE_AMOUNT="${USAGE_AMOUNT:-1200}" # deliberately > TIER1_MAX to exercise both tiers +TODAY=$(date +%F) +run_curl 201 /tmp/usage_response.json \ + -X POST "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + -H "Content-Type: application/json" \ + -d "{\"subscriptionId\": \"${SUBSCRIPTION_ID}\", \"unitUsageRecords\": [{\"unitType\": \"${UNIT_NAME}\", \"usageRecords\": [{\"recordDate\": \"${TODAY}\", \"amount\": ${USAGE_AMOUNT}}]}]}" \ + "${KB_URL}/1.0/kb/usages" +echo "Recorded ${USAGE_AMOUNT} units of ${UNIT_NAME} on ${TODAY}" + +echo +echo "=== Step 6: Dry-run invoice preview (shows accrued usage charge) ===" +curl -s "${AUTH[@]}" "${TENANT_HEADERS[@]}" "${CREATED_BY[@]}" \ + "${KB_URL}/1.0/kb/invoices/dryRun?accountId=${ACCOUNT_ID}&targetDate=$(date -d '+1 month' +%F 2>/dev/null || date -v+1m +%F)" \ + -X POST -H "Content-Type: application/json" -d "{\"dryRunType\": \"TARGET_DATE\"}" | jq . + +echo +echo "=== Done ===" +echo "Note: the dry-run above may show \$0 usage if the current billing period hasn't closed yet;" +echo "consumable-in-arrear usage is only billed at the END of its billing period." +```` + ## Decision guidance ### When to use API vs Kaui vs plugin From 91dd67db44dc07daa7f58c0c69099fb5d3d9ec79 Mon Sep 17 00:00:00 2001 From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com> Date: Wed, 22 Jul 2026 13:23:48 +0530 Subject: [PATCH 4/4] add reference to MCP server --- latest/skill.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/latest/skill.md b/latest/skill.md index d48388820..c5e151466 100644 --- a/latest/skill.md +++ b/latest/skill.md @@ -17,6 +17,7 @@ Kill Bill is an open-source subscription billing and payments platform. It handl - Client libraries: `killbill-client-java`, `killbill-client-python`, `killbill-client-ruby`, `killbill-client-js` - Plugin manager (KPM): Used to install plugins using `kpm install_java_plugin ` - Docker: `killbill/killbill` and `killbill/kaui` images +- - MCP server: `apidocs-mcp.killbill.io` — provides direct access to Kill Bill API documentation; can generate accurate, up-to-date API usage examples and scripts **Authentication:** HTTP Basic Auth (`-u :`) plus required multi-tenancy headers `X-Killbill-ApiKey` and `X-Killbill-ApiSecret`. Every mutating call should also include `X-Killbill-CreatedBy` (and optionally `X-Killbill-Reason` / `X-Killbill-Comment`). @@ -54,7 +55,8 @@ Use this skill whenever users ask about: When answering questions: -1. Prefer official Kill Bill documentation over assumptions. +1. On loading this skill, check whether an MCP connector for `apidocs-mcp.killbill.io` is available/connected. If it is not connected, ask the user whether they'd like to connect it before proceeding — it provides direct, current API documentation and can generate accurate code snippets, reducing reliance on this skill's own static examples or on web search. +2. Prefer official Kill Bill documentation over assumptions. 2. Mention version-specific behavior when relevant. 3. If multiple approaches exist, recommend the simplest supported approach first. 4. Prefer configuration over custom code when possible.