Kill Bill Kintsugi Tax Plugin

Kill Bill invoice plugin that delegates sales tax to Kintsugi during invoice generation.

What it does

On each invoice (dry-run or commit), the plugin:

1. Maps Kill Bill invoice line items and account ship-to address to a tax estimate request
2. Calls POST /killbill/tax/estimate or /commit on your Kintsugi API
3. Maps tax lines to Kill Bill TAX invoice items linked to taxable lines

Authentication on every call:

Header	Value
X-Killbill-ApiKey	Kill Bill tenant API key (must match your Kintsugi Kill Bill connection)
X-Killbill-Kintsugi-Signature	HMAC-SHA256 hex digest of the raw JSON body

The HMAC secret is stored on both the Kill Bill plugin config (hmacSecret) and the Kintsugi connection. In the product flow Kintsugi generates it and uploads plugin config when you Enable Tax Collection — you do not paste a secret by hand.

Prerequisites

• JDK 11+
• Maven 3.9+ (build from source) or a release JAR
• Kill Bill 0.24.x with invoice plugin support
• A Kintsugi account with Kill Bill connected and tax collection enabled

Kill Bill compatibility

Plugin version	Kill Bill
0.1.x	0.24.x

Build and test

mvn clean verify

Docker E2E (recommended for maintainers): see docker/README.md.

Artifact: target/kintsugi-plugin-0.1.0.jar

Install on Kill Bill

Option A: KPM (recommended when a release is published)

kpm install_java_plugin kintsugi --from-source-file=target/kintsugi-plugin-0.1.0.jar

Or install a published artifact from Maven Central once the Kill Bill project publishes org.kill-bill.billing.plugin.java:kintsugi-plugin — see Kill Bill KPM. Until a release is published on this repository, build from source or use a maintainer-built JAR from GitHub releases.

Option B: Manual copy

1. Copy the JAR into Kill Bill's Java plugin layout, e.g.
   /var/lib/killbill/bundles/plugins/java/killbill-kintsugi/0.1.0/kintsugi-plugin-0.1.0.jar
2. Set the default version symlink if your deployment uses one.
3. Restart Kill Bill and confirm the plugin is RUNNING with InvoicePluginApi in GET /1.0/kb/pluginsInfo.

See Kill Bill plugin installation.

Tenant configuration

After the plugin JAR is installed and running on Kill Bill, configure the tenant from Kintsugi (no manual uploadPluginConfig / uploadPerTenantConfig curls):

1. In Kintsugi, Connect Kill Bill (base URL, tenant API key/secret, admin username/password).
2. Click Enable Tax Collection on the connection.

Kintsugi then generates an HMAC secret (if needed), uploads plugin config (kintsugiUrl + hmacSecret), and enables killbill-kintsugi as the tenant invoice plugin. You do not paste secrets by hand.

For local docker / maintainer smoke tests that talk to Kill Bill without the product UI, see docker/README.md.

Config key	Required	Description
kintsugiUrl	Yes	Kintsugi API base URL (no trailing slash), e.g. https://api.trykintsugi.com — set by Enable Tax
hmacSecret	Yes	Shared secret for request signatures — generated and uploaded by Enable Tax
killbillUrl	No	Kill Bill base URL for optional Aviate billing-account lookup (default http://127.0.0.1:8080)
aviateIdToken	No	Aviate JWT (Aviate auth). When set, the plugin reads billing accounts before falling back to custom fields. Omit for non-Aviate deployments.

kintsugiUrl must be reachable from the Kill Bill JVM (network/firewall/DNS).

To inspect the stored tenant plugin config (not the healthcheck):

curl -u '<killbill-admin-user>:<killbill-admin-password>' \
  -H 'X-Killbill-ApiKey: <tenant-api-key>' \
  -H 'X-Killbill-ApiSecret: <tenant-api-secret>' \
  'https://<killbill-host>/1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi'

See Kintsugi documentation for the full setup guide.

Verify

After configuration, generate or dry-run an invoice for an account with taxable line items. The invoice should include TAX rows linked to taxable EXTERNAL_CHARGE or subscription lines when Kintsugi returns non-zero tax.

Check Kill Bill logs for Kintsugi returned N tax line(s) from KintsugiInvoicePluginApi.

Healthcheck

curl -u '<killbill-admin-user>:<killbill-admin-password>' \
  -H 'X-Killbill-ApiKey: <tenant-api-key>' \
  -H 'X-Killbill-ApiSecret: <tenant-api-secret>' \
  'https://<killbill-host>/plugins/killbill-kintsugi/healthcheck'

Healthy response (plugin loaded and tenant config present):

{"message":"Kintsugi plugin configured"}

The healthcheck does not return kintsugiUrl or hmacSecret. To read those values, use GET .../uploadPluginConfig/killbill-kintsugi (see above).

Local development

Maintainers: use the self-contained docker toolkit (no Kintsugi platform repo required):

cp docker/.env.example docker/.env
./docker/run-e2e.sh

See docker/README.md for step-by-step scripts, configuration, and troubleshooting.

Troubleshooting

Symptom	Likely cause
No TAX lines on invoice	Tax collection not enabled in Kintsugi, or ship-to address has no tax obligation
401 / 403 from Kintsugi	HMAC mismatch — re-run Enable Tax Collection (re-uploads matching secret)
Kintsugi plugin not configured in logs	Tenant plugin config missing — re-run Enable Tax Collection
Connection timeout	Kill Bill cannot reach kintsugiUrl (DNS, firewall, or Docker networking)
Healthcheck unhealthy	Plugin config missing kintsugiUrl or hmacSecret for the tenant — re-run Enable Tax Collection
Expected config keys in healthcheck body	Wrong endpoint — healthcheck only returns {"message":"..."}; use GET .../uploadPluginConfig/killbill-kintsugi to inspect

Behavior notes

• Dual deployment: Aviate tenants — the Aviate plugin will pass plugin properties on invoice generation; optional aviateIdToken fills gaps via billing-account HTTP. Non-Aviate tenants use custom fields only.
• HTTP/1.1: outbound calls use HTTP/1.1 so request bodies match HMAC signatures reliably.
• External charges: lines without a plan name use a default product category.
• Retries: transient failures raise InvoicePluginApiRetryException (1m / 5m / 15m backoff).
• Zero tax: $0 tax lines are not added to the invoice.

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md.

Maven Central publishing is handled by the Kill Bill project after upstream transfer; see docs/maven-central-handoff.md.

Local testing: docker/README.md.

License

Apache License 2.0 — see LICENSE.