Skip to content

Add Kintsugi tax invoice plugin v0.1.0 - #1

Open
JeffTax wants to merge 2 commits into
killbill:mainfrom
JeffTax:chore/no-ref/handover-to-killbill-org
Open

Add Kintsugi tax invoice plugin v0.1.0#1
JeffTax wants to merge 2 commits into
killbill:mainfrom
JeffTax:chore/no-ref/handover-to-killbill-org

Conversation

@JeffTax

@JeffTax JeffTax commented Jul 7, 2026

Copy link
Copy Markdown

Initial contribution of the Kintsugi sales tax invoice plugin.

  • Java OSGi invoice plugin (killbill-kintsugi) that delegates tax calculation to Kintsugi during invoice generation (POST /killbill/tax/estimate and /commit)
  • HMAC-SHA256 request signing, re-invoice idempotency, and dual-path tax metadata (plugin properties / custom fields, optional Aviate billing-account lookup)
  • TestNG fast suite with WireMock, healthcheck servlet, docker E2E toolkit, and CI via killbill/gh-actions-shared
  • Maven coordinates: org.kill-bill.billing.plugin.java:kintsugi-plugin:0.1.0

See the README for install, tenant configuration, and troubleshooting. Maintainer notes for Central publish and docs.killbill.io live under docs/.

How to test

mvn clean verify

Requires JDK 11. Optional docker E2E: docker/run-e2e.sh (needs a Kintsugi test org).

@JeffTax
JeffTax force-pushed the chore/no-ref/handover-to-killbill-org branch 2 times, most recently from 33c4fb3 to fad0fd6 Compare July 7, 2026 21:07
OSGi invoice plugin delegating tax to Kintsugi with HMAC auth, re-invoice
idempotency, properties-first dual-path metadata (Aviate + custom fields),
optional Aviate billing-account HTTP, healthcheck servlet, TestNG/WireMock
tests, docker maintainer toolkit, and CI via killbill/gh-actions-shared.

Includes document-level tax error retries and Mosaic line_external_id /
rate_percentage response field mapping.
@JeffTax
JeffTax force-pushed the chore/no-ref/handover-to-killbill-org branch from fad0fd6 to 289feba Compare September 3, 2026 16:59
@JeffTax JeffTax changed the title chore/no-ref: add kintsugi tax invoice plugin v0.1.0 Add Kintsugi tax invoice plugin v0.1.0 Sep 3, 2026
@reshmabidikar

Copy link
Copy Markdown

I had to add the following dependency to the pom:

<dependency>
            <groupId>org.kill-bill.commons</groupId>
            <artifactId>killbill-utils</artifactId>
            <scope>runtime</scope>
</dependency>

Without this, the plugin results in the following exception:

123319-java.lang.ClassNotFoundException: org.killbill.commons.utils.collect.Iterables not found by org.kill-bill.billing.plugin.java.kintsugi-plugin [11]
123320- at org.killbill.billing.plugin.api.PluginProperties.findPluginPropertyValue(PluginProperties.java:89)
123321- at com.trykintsugi.killbill.internal.TaxInputMetadataLoader.resolveCustomerUsageType(TaxInputMetadataLoader.java:71)
123322- at com.trykintsugi.killbill.internal.TaxInputMetadataLoader.load(TaxInputMetadataLoader.java:55)
123323- at com.trykintsugi.killbill.internal.TaxMetadataResolver.resolve(TaxMetadataResolver.java:67)
123324- at com.trykintsugi.killbill.KintsugiInvoicePluginApi.getAdditionalInvoiceItems(KintsugiInvoicePluginApi.java:94)
123325- at com.trykintsugi.killbill.KintsugiInvoicePluginApi.getAdditionalInvoiceItems(KintsugiInvoicePluginApi.java:46)
123326- at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
123327- at java.base/java.lang.reflect.Method.invoke(Method.java:580)

PluginProperties.findPluginPropertyValue needs
org.killbill.commons.utils.collect.Iterables from the OSGi bundle.
Without killbill-utils as a runtime dependency, invoice generation
fails with ClassNotFoundException — same pattern as stripe/vertex plugins.
@JeffTax

JeffTax commented Sep 4, 2026

Copy link
Copy Markdown
Author

Thanks @reshmabidikar — added org.kill-bill.commons:killbill-utils with runtime scope (same as stripe/vertex plugins) so PluginProperties can resolve Iterables inside the OSGi bundle.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants