Skip to content

Commit 9cec787

Browse files
reshmabidikarreshmabidikar
authored
Merge pull request #709 from reshmabidikar/kintsugi-plugin-docs
Kintsugi doc
2 parents 4dc7770 + 1420dce commit 9cec787

2 files changed

Lines changed: 300 additions & 0 deletions

File tree

‎html5/_main_toc.html.slim‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,9 @@ nav.sidebar-nav
187187
li
188188
a.nav-link href="/latest/braintree-plugin.html"
189189
| Braintree Plugin
190+
li
191+
a.nav-link href="/latest/kintsugi-plugin.html"
192+
| Kintsugi Plugin
190193
li
191194
a.nav-link href="/latest/notification_plugin.html"
192195
| Notification Plugins

‎userguide/tutorials/kintsugi-plugin.adoc‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
= Kintsugi Tax Plugin Tutorial
2+
3+
== Prerequisites
4+
5+
You will need:
6+
7+
* A running Kill Bill instance (0.24.x) and Kaui, set up as explained in the
8+
getting_started.html[Getting Started Guide].
9+
* https://curl.haxx.se/[cURL] installed. On Windows, we recommend
10+
https://git-scm.com/download/win[Git Bash] to run the `curl` commands.
11+
* A Kintsugi account, with Kill Bill connected as described in <<step_5,Step 5>>.
12+
13+
== Overview
14+
15+
The https://github.com/killbill/killbill-kintsugi-plugin[Kintsugi Tax Plugin] is a Kill Bill invoice plugin that delegates sales tax calculation to https://trykintsugi.com[Kintsugi] during invoice generation. On each invoice (dry-run or commit), the plugin invokes the Kintsugi API and maps the returned tax lines to `TAX` invoice items linked to the taxable lines.
16+
17+
This tutorial walks through a full end-to-end scenario: installing the plugin, configuring a tenant, syncing the catalog with Kintsugi, registering a jurisdiction, and verifying that an invoice picks up the correct tax.
18+
19+
== How It Works
20+
21+
For developers, the Kintsugi plugin is implemented as an https://docs.killbill.io/latest/invoice_plugin[Kill Bill Invoice Plugin]. It implements the
22+
https://github.com/killbill/killbill-plugin-api/blob/a20776687fc61ce4ca94d84e2b117e4cce0a255c/invoice/src/main/java/org/killbill/billing/invoice/plugin/api/InvoicePluginApi.java#L39[getAdditionalInvoiceItems]
23+
method. On each invoice (dry-run or commit), it:
24+
25+
. Maps Kill Bill invoice line items and the account's ship-to address to a tax estimate request.
26+
. Calls `POST /killbill/tax/estimate` or `/commit` on the Kintsugi API.
27+
. Maps the returned tax lines to Kill Bill `TAX` invoice items linked to the taxable lines.
28+
29+
Every call to Kintsugi API authenticated with two headers:
30+
31+
|===
32+
|Header |Value
33+
34+
|`X-Killbill-ApiKey`
35+
|Kill Bill tenant API key (must match the Kintsugi Kill Bill connection).
36+
37+
|`X-Killbill-Kintsugi-Signature`
38+
|HMAC-SHA256 hex digest of the raw JSON request body, signed with the shared `hmacSecret`.
39+
|===
40+
41+
=== Behavior Notes
42+
43+
* *Dual deployment*: for Aviate tenants, the Aviate plugin passes plugin properties on invoice generation; the optional `aviateIdToken` fills gaps via billing-account HTTP lookups. Non-Aviate tenants use custom fields only.
44+
* *HTTP/1.1*: outbound calls to Kintsugi use HTTP/1.1 so request bodies match HMAC signatures reliably.
45+
* *External charges*: line items without a plan name use a default product category.
46+
* *Retries*: transient failures raise `InvoicePluginApiRetryException`, retried after 1, 5, and 15 minutes.
47+
* *Zero tax*: `$0` tax lines are not added to the invoice.
48+
49+
[[plugin_installation]]
50+
== Plugin Installation
51+
52+
//Add Aviate installation steps once the plugin is available in the Aviate marketplace
53+
54+
Install the plugin using https://github.com/killbill/killbill-cloud/blob/master/kpm[KPM]:
55+
56+
[source,bash]
57+
----
58+
kpm install_java_plugin kintsugi --from-source-<source_file_path>/kintsugi-plugin-0.1.0.jar --destination=<path_to_install_plugin>
59+
----
60+
61+
Confirm the plugin is `RUNNING` with `InvoicePluginApi` listed:
62+
63+
[source,bash]
64+
----
65+
curl -v \
66+
-u admin:password \
67+
http://127.0.0.1:8080/1.0/kb/nodesInfo
68+
----
69+
70+
== Plugin Configuration
71+
72+
In order to enable the Kintsugi plugin, the following property needs to be set in the
73+
https://docs.killbill.io/latest/userguide_configuration#global_configuration_properties[Kill Bill Configuration File],
74+
or at a https://docs.killbill.io/latest/userguide_configuration#_per_tenant_properties[per-tenant level]:
75+
76+
[source,bash]
77+
----
78+
org.killbill.invoice.plugin=killbill-kintsugi
79+
----
80+
81+
In addition, the Kintsugi plugin requires the following properties, uploaded via
82+
`uploadPluginConfig/killbill-kintsugi`:
83+
84+
|===
85+
|Property |Required |Description
86+
87+
|`kintsugiUrl`
88+
|Yes
89+
|Kintsugi API base URL (no trailing slash), reachable from the Kill Bill JVM.
90+
91+
|`hmacSecret`
92+
|Yes
93+
|Shared secret; must match the HMAC secret on the Kintsugi Kill Bill connection.
94+
95+
|`killbillUrl`
96+
|No
97+
|Kill Bill base URL for optional Aviate billing-account lookup (default `+http://127.0.0.1:8080+`).
98+
99+
|`aviateIdToken`
100+
|No
101+
|Aviate JWT. When set, the plugin reads Aviate billing accounts before falling back to custom
102+
fields. Omit for non-Aviate deployments.
103+
|===
104+
105+
These properties can be configured on a per-tenant basis via the https://apidocs.killbill.io/tenant#add-a-per-tenant-configuration-for-a-plugin[Add a per-tenant configuration for a plugin] endpoint. For example, to configure these properties for the `bob/lazar` tenant, you can use the following curl:
106+
107+
[source, bash]
108+
----
109+
curl -u 'admin:password' \
110+
-H 'X-Killbill-ApiKey: bob' \
111+
-H 'X-Killbill-ApiSecret: lazar' \
112+
-H 'Content-Type: text/plain' \
113+
-H 'X-Killbill-CreatedBy: setup' \
114+
-d 'kintsugiUrl: https://api.trykintsugi.com
115+
hmacSecret: <shared-hmac-secret>' \
116+
'https://<killbill-host>/1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi'
117+
----
118+
119+
== Testing the Plugin
120+
121+
Once the plugin is installed and configured, you can use it to generate tax items. This section provides an end to end tutorial.
122+
123+
=== Step 1: Install the Plugin
124+
125+
Ensure that the plugin is installed as explained in the <<plugin_installation, "Plugin Installation">> section.
126+
127+
=== Step 2: Create a Tenant
128+
129+
We start by creating a tenant `tax-scenario`, using the standard https://apidocs.killbill.io/tenant.html#create-a-tenant[Create Tenant] API:
130+
131+
[source,bash]
132+
----
133+
curl -v -X POST -u admin:password \
134+
-H "Content-Type: application/json" \
135+
-H "Accept: application/json" \
136+
-H "X-Killbill-CreatedBy: demo" \
137+
-d '{ "apiKey": "tax-scenario", "apiSecret": "tax-scenario" }' \
138+
"http://127.0.0.1:8080/1.0/kb/tenants"
139+
----
140+
141+
[[step_3]]
142+
=== Step 3: Enable the Kintsugi Invoice Plugin
143+
144+
Enable the kintsugi plugin for the tenant created above:
145+
146+
[source,bash]
147+
----
148+
curl -u admin:password \
149+
-H "X-Killbill-ApiKey: tax-scenario" \
150+
-H "X-Killbill-ApiSecret: tax-scenario" \
151+
-H "Content-Type: text/plain" \
152+
-H "X-Killbill-CreatedBy: setup" \
153+
-d '{"org.killbill.invoice.plugin":"killbill-kintsugi"}' \
154+
"http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig"
155+
----
156+
157+
[[step_4]]
158+
=== Step 4: Set up the Catalog
159+
160+
Configure the catalog for the tenant. You can do this easily via the
161+
https://docs.killbill.io/latest/aviate-catalog-guide[Aviate UI].
162+
163+
Alternatively, you can also upload an XML catalog via the
164+
https://apidocs.killbill.io/catalog#upload-a-catalog-as-xml[Upload Catalog] API:
165+
166+
[source,bash]
167+
----
168+
curl -v \
169+
-X POST \
170+
-u admin:password \
171+
-H "X-Killbill-ApiKey: tax-scenario" \
172+
-H "X-Killbill-ApiSecret: tax-scenario" \
173+
-H "Content-Type: text/xml" \
174+
-H "Accept: application/json" \
175+
-H "X-Killbill-CreatedBy: demo" \
176+
-H "X-Killbill-Reason: demo" \
177+
-H "X-Killbill-Comment: demo" \
178+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><catalog> ... </catalog>' \
179+
"http://127.0.0.1:8080/1.0/kb/catalog/xml"
180+
----
181+
182+
[[step_5]]
183+
=== Step 5: Add the Tenant in Kintsugi
184+
185+
In the Kintsugi app, click on "Data Sources" in the left nav, select "Kill Bill" as the integration and enter the following details:
186+
187+
- Kill Bill base URL ( for example `https://api.killbill.dev`). The URL must use HTTPS.
188+
- Tenant API key (`tax-scenario`)
189+
- Tenant API secret (`tax-scenario`)
190+
- Admin username (`admin`)
191+
- Admin password (`password`)
192+
193+
Kintsugi then syncs the catalog from Kill Bill. This sync typically takes *10 to 15 minutes* to complete.
194+
195+
[[step_6]]
196+
=== Step 6: Categorize the Synced Products
197+
198+
Once the sync completes, click on the "Products" link in the left nav. The products from the catalog configured in <<step_4, Step 4>> appear in the Kintsugi app. Assign a tax category to each product from the Kintsugi products screen so that Kintsugi knows how to tax it.
199+
200+
=== Step 7: Enable Tax Collection
201+
202+
In the Kintsugi app, click on "Data Sources" in the left nav. Click the "Enable tax collection" button for the integration added in <<step_5, Step 5>> above.
203+
204+
This step adds the kintsugi plugin configuration for the tenant and can be verified as follows:
205+
206+
[source,bash]
207+
----
208+
curl -v \
209+
-u admin:password \
210+
-H "X-Killbill-ApiKey: tax-scenario" \
211+
-H "X-Killbill-ApiSecret: tax-scenario" \
212+
-H "Accept: application/json" \
213+
"http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi"
214+
----
215+
216+
217+
[[step_8]]
218+
=== Step 8: Create a Jurisdiction
219+
220+
In the Kintsugi app, click on "Data Sources" in the left nav. Create a jurisdiction for each region you want to collect tax in. For this tutorial, create a jurisdiction for *California*.
221+
222+
=== Step 9: Create an Account
223+
224+
Open the `tax-scenario` tenant in Kaui and create an account with a zip code that falls within
225+
the jurisdiction registered in <<step_8, Step 8>>. For California, use zip code `94101`.
226+
227+
Alternatively, you can also create an account via the
228+
https://apidocs.killbill.io/account#create-an-account[Create Account] API:
229+
230+
[source,bash]
231+
----
232+
curl -v -X POST -u admin:password \
233+
-H "X-Killbill-ApiKey: tax-scenario" \
234+
-H "X-Killbill-ApiSecret: tax-scenario" \
235+
-H "Content-Type: application/json" \
236+
-H "X-Killbill-CreatedBy: demo" \
237+
-d '{ "name": "John Doe", "email": "john@example.com", "currency": "USD", "address1": "123 Main Street", "city": "San Francisco", "state": "CA", "country": "US", "postalCode": "94101" }' \
238+
"http://127.0.0.1:8080/1.0/kb/accounts"
239+
----
240+
241+
=== Step 10: Create a Subscription
242+
243+
Create a subscription for the account either via Kaui or via the
244+
https://apidocs.killbill.io/subscription#create-a-subscription[Create Subscription] API:
245+
246+
[source,bash]
247+
----
248+
curl -v -X POST -u admin:password \
249+
-H "X-Killbill-ApiKey: tax-scenario" \
250+
-H "X-Killbill-ApiSecret: tax-scenario" \
251+
-H "Content-Type: application/json" \
252+
-H "X-Killbill-CreatedBy: demo" \
253+
-d '{ "accountId": "{accountId}", "planName": "{planName}" }' \
254+
"http://127.0.0.1:8080/1.0/kb/subscriptions"
255+
----
256+
257+
=== Step 11: Verify the Invoice
258+
259+
Check the invoices either via Kaui. Alternatively, you can retrieve the account's invoices, using the standard
260+
link:https://apidocs.killbill.io/account#retrieve-account-invoices[Retrieve Account Invoices] API:
261+
262+
[source,bash]
263+
----
264+
curl -v -u admin:password \
265+
-H "X-Killbill-ApiKey: tax-scenario" \
266+
-H "X-Killbill-ApiSecret: tax-scenario" \
267+
-H "Accept: application/json" \
268+
"http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices"
269+
----
270+
271+
*Expected result:* the invoice generated for the subscription includes a `TAX` line item linked
272+
to the subscription line, computed by Kintsugi for the California jurisdiction.
273+
274+
If no `TAX` line appears, check the Kill Bill logs for `Kintsugi returned N tax line(s)` from
275+
`KintsugiInvoicePluginApi`, and see the Troubleshooting section below.
276+
277+
== Troubleshooting
278+
279+
|===
280+
|Symptom |Likely cause
281+
282+
|No `TAX` lines on invoice
283+
|Tax collection not enabled in Kintsugi (<<step_3, Step 3>>), the product isn't
284+
categorized (<<step_6, Step 6>>), or the account's zip code falls
285+
outside a registered jurisdiction (<<step_8, Step 8>>).
286+
287+
|`Kintsugi plugin not configured` in logs
288+
|Tax collection not enabled in Kintsugi (<<step_3, Step 3>>).
289+
290+
|Connection timeout
291+
|Kill Bill cannot reach `kintsugiUrl` (DNS, firewall, or Docker networking).
292+
293+
|Products not showing up in Kintsugi
294+
|The catalog sync (<<step_5, Step 5>>) hasn't completed yet — it can take 10 to 15 minutes.
295+
|===
296+
297+

0 commit comments

Comments
 (0)