Skip to content

Commit 26f1f3a

Browse files
reshmabidikarreshmabidikar
authored
Merge pull request killbill#624 from reshmabidikar/work-for-ts-220
Aviate tax documentation
2 parents c2854cb + 981c28d commit 26f1f3a

File tree

4 files changed

+356
-3
lines changed

4 files changed

+356
-3
lines changed

‎html5/_main_toc.html.slim‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -374,9 +374,15 @@ nav.sidebar-nav
374374
li.bd-sidenav-active
375375
a.nav-link href="/latest/aviate-coupons.html"
376376
| Coupons
377+
li.bd-sidenav-active
378+
a.nav-link href="/latest/aviate-tax.html"
379+
| Tax
377380
li.bd-sidenav-active
378381
a.nav-link href="/latest/aviate-usage-ai-tutorial.html"
379382
| Usage Tutorial (AI use case)
383+
li.bd-sidenav-active
384+
a.nav-link href="/latest/aviate-tax-tutorial.html"
385+
| Tax Tutorial
380386
li
381387
.icon-title
382388
a.bd-toc-link.main-link role="button"

‎userguide/aviate/aviate-custom-invoice-sequencing.adoc‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
= Aviate Custom Invoice Sequencing
22

3+
include::{sourcedir}/aviate/includes/aviate-card.adoc[]
4+
35
The Aviate Custom Invoice Sequencing feature enables the use of customized invoice numbering sequences. The core Kill Bill module uses a sequential numbering scheme for invoice numbers. This is common across accounts/tenants. While this is good enough for most use cases, some situations might require a tailored numbering sequence to meet specific business needs. This functionality is made possible through the Aviate Custom Invoice Sequencing feature.
46

57
== Getting Started with Aviate Custom Invoice Sequencing
@@ -50,9 +52,6 @@ Here:
5052

5153
Once the above configuration is done, any invoices created will start with `300001` and continue forward.
5254

53-
[NOTE]
54-
*Note:* At the time of writing, custom invoice sequencing is not implemented for invoice/email templates.
55-
5655
== Using Custom Invoice Sequencing
5756

5857
Once the above configuration is done, all the invoices generated will use the custom sequencing as can be seen in the screenshot below:

‎userguide/aviate/aviate-tax-tutorial.adoc‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
= Aviate Tax Tutorial
2+
3+
include::{sourcedir}/aviate/includes/aviate-card.adoc[]
4+
5+
== Introduction
6+
7+
This document provides a tutorial on using the aviate tax feature.
8+
9+
== Prerequisites
10+
11+
You will need:
12+
13+
* A running Kill Bill instance with the Aviate plugin installed.
14+
* A valid API access tokens for all Aviate APIs calls - referred to as `ID_TOKEN`
15+
16+
== Setup: Configuring a Tenant
17+
18+
=== Step 1: Create a tenant
19+
20+
We start by creating a tenant `tax-scenario`.
21+
22+
Use the standard https://killbill.github.io/slate/tenant.html#create-a-tenant[Create Tenant] Kill Bill API:
23+
24+
[source,bash]
25+
-----
26+
curl -v -X POST -u admin:password \
27+
-H "Content-Type: application/json" \
28+
-H "Accept: application/json" \
29+
-H "X-Killbill-CreatedBy: demo" \
30+
-d '{ "apiKey": "tax-scenario", "apiSecret": "tax-scenario" }' \
31+
"http://127.0.0.1:8080/1.0/kb/tenants"
32+
-----
33+
34+
=== Step 2: Create a catalog
35+
36+
Upload an XML catalog or create a plan/product via the Aviate Catalog APIs.
37+
38+
To upload an XML catalog, you can use the standard https://apidocs.killbill.io/catalog#upload-a-catalog-as-xml[Upload Catalog API]:
39+
40+
[source,bash]
41+
-----
42+
curl -v \
43+
-X POST \
44+
-u admin:password \
45+
-H "X-Killbill-ApiKey: tax-scenario" \
46+
-H "X-Killbill-ApiSecret: tax-scenario" \
47+
-H "Content-Type: text/xml" \
48+
-H "Accept: application/json" \
49+
-H "X-Killbill-CreatedBy: demo" \
50+
-H "X-Killbill-Reason: demo" \
51+
-H "X-Killbill-Comment: demo" \
52+
-d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><catalog> ...' \
53+
"http://127.0.0.1:8080/1.0/kb/catalog/xml"
54+
-----
55+
56+
Alternatively, you can create a plan/product via the Aviate Catalog https://apidocs.killbill.io/aviate-catalog#create-plan-product-pricelist[Create Plan, Product, Pricelist] API:
57+
58+
[source, bash]
59+
----
60+
curl -X POST \
61+
-H'Content-Type: application/json' \
62+
-H"Authorization: Bearer ${ID_TOKEN}" \
63+
-H'X-killbill-apiKey: tax-scenario' \
64+
-H'X-killbill-apisecret: tax-scenario' \
65+
-d '{
66+
"plans": [
67+
{
68+
"name": "premium-annual",
69+
"prettyName": "Premium Annual",
70+
"recurringBillingMode": "IN_ADVANCE",
71+
"pricelistName": "DEFAULT",
72+
"productName": "Premium",
73+
"phases": [
74+
{
75+
"prettyName": "Premium Annual Evergreen",
76+
"type": "EVERGREEN",
77+
"durationUnit": "UNLIMITED",
78+
"durationLength": -1,
79+
"fixedPrices": [
80+
{
81+
"currency": "USD",
82+
"value": "0.50"
83+
}
84+
],
85+
"recurringPrices": {
86+
"billingPeriod": "ANNUAL",
87+
"prices": [
88+
{
89+
"currency": "USD",
90+
"value": "15"
91+
}
92+
]
93+
}
94+
}
95+
]
96+
}
97+
],
98+
"products": [
99+
{
100+
"name": "Premium",
101+
"category": "BASE"
102+
}
103+
]
104+
}' \
105+
http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/inputData
106+
----
107+
108+
109+
=== Step 3: Configure the tax related properties for the product
110+
111+
The next step would be to configure the tax related information for the product created in Step 2. Assuming that you want the "Premium" product to be taxed at a rate of 19.6% for invoices created between 2025-01-01 to 2025-03-31 and at a rate of 20% for invoices created after 2025-03-31 when country is `US`, you can configure the plugin as follows:
112+
113+
[source, bash]
114+
----
115+
curl -v \
116+
-X POST \
117+
-u admin:password \
118+
-H 'X-Killbill-ApiKey: tax-scenario' \
119+
-H 'X-Killbill-ApiSecret: tax-scenario' \
120+
-H 'X-Killbill-CreatedBy: admin' \
121+
-H 'Content-Type: text/plain' \
122+
-d '!!com.killbill.billing.plugin.aviate.AviateTenantConfig
123+
taxConfig:
124+
taxItemAmountPrecision: 2
125+
taxationTimeZone: UTC
126+
taxCodes:
127+
TAX_US_std_2025_19_6:
128+
description: Sales Tax 19.6%
129+
rate: 0.196
130+
startingOn: 2025-01-01
131+
stoppingOn: 2025-03-31
132+
country: US
133+
TAX_US_std_2025_20_0:
134+
description: Sales Tax 20%
135+
rate: 0.200
136+
startingOn: 2025-04-01
137+
stoppingOn: ""
138+
country: US
139+
products:
140+
Premium: TAX_US_std_2000_19_6, TAX_US_std_2014_20_0' \
141+
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/aviate-plugin
142+
----
143+
144+
== Creating a Customer Account
145+
146+
=== Step 1: Create a new account
147+
148+
Use the standard Kill Bill https://killbill.github.io/slate/account.html#create-an-account[Create Account] API:
149+
150+
[source,bash]
151+
-----
152+
curl -v -X POST -u admin:password \
153+
-H "X-Killbill-ApiKey: tax-scenario" \
154+
-H "X-killbill-apisecret: tax-scenario" \
155+
-H "X-Killbill-CreatedBy: demo" \
156+
-H "Content-Type: application/json" \
157+
-d '{ "name": "John Doe", "email": "john.doe@somewhere.com", "currency": "USD" }' \
158+
"http://127.0.0.1:8080/1.0/kb/accounts"
159+
-----
160+
161+
=== Step 2: Create a billing account
162+
163+
Use the Aviate Create Billing Account API to create a billing account corresponding to the account. Ensure that the appropriate country is specified as part of taxRegistration#address:
164+
165+
[source, bash]
166+
----
167+
curl -X POST \
168+
-H'Content-Type: application/json' \
169+
-H'X-killbill-apiKey: tax-scenario' \
170+
-H'X-killbill-apisecret: tax-scenario' \
171+
-d '{ "kbAccountId":"e5d3d5b5-4415-4166-b57f-33ca00a59e88", "taxRegistrations": [{
172+
"name": "John Doe",
173+
"exempt": false,
174+
"trn": "TRN-987654",
175+
"address": {
176+
"addressLine1": "123 Main Street",
177+
"addressLine2": "Suite 4B",
178+
"city": "Springfield",
179+
"state": "Illinois",
180+
"country": "US",
181+
"postalCode": "62701"
182+
}
183+
}]}' \
184+
http://127.0.0.1:8080/plugins/aviate-plugin/v1/ba
185+
----
186+
187+
=== Step 3: Create a subscription
188+
189+
Create a subscription to the `premium-monthly` plan. Use the standard Kill Bill https://apidocs.killbill.io/subscription#create-a-subscription[Create Subscription] API:
190+
191+
[source,bash]
192+
-----
193+
curl -v -X POST -u admin:password \
194+
-H "X-Killbill-ApiKey: tax-scenario" \
195+
-H "X-killbill-apisecret: tax-scenario" \
196+
-H "X-Killbill-CreatedBy: demo" \
197+
-H "Content-Type: application/json" \
198+
-d '{ "accountId": "{accountId}", "planName": "premium-monthly" }' \
199+
"http://127.0.0.1:8080/1.0/kb/subscriptions"
200+
-----
201+
202+
=== Step 4: Retrieve Invoices
203+
204+
205+
Use the standard Kill Bill https://apidocs.killbill.io/account#retrieve-account-invoices[Retrieve Account Invoices] API:
206+
207+
[source,bash]
208+
----
209+
curl -v \
210+
-u admin:password \
211+
-H "X-Killbill-ApiKey: tax-scenario" \
212+
-H "X-Killbill-ApiSecret: tax-scenario" \
213+
-H "Accept: application/json" \
214+
"http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices"
215+
----
216+
217+
Ensure that the invoice corresponding to the subscription includes a tax item. Assuming the base subscription price is `$100`, it should be taxed at *20%*. So the tax item should be for `$20`.
218+

‎userguide/aviate/aviate-tax.adoc‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
= Aviate Tax
2+
3+
include::{sourcedir}/aviate/includes/aviate-card.adoc[]
4+
5+
== Introduction
6+
7+
The Aviate Tax feature enables tax functionality within the Aviate plugin. It allows you to configure country-specific tax codes. These tax codes can then be assigned to different products. When a subscription is created for a product with an associated tax code, the system automatically generates a tax invoice item based on the configured tax rate.
8+
9+
Each tax code is defined with a validity window that determines when it applies. The correct tax code is chosen based on the **invoice item end date**. Tax codes are country-level only (subdivisions such as states or provinces are not yet supported), and they apply only if the account’s tax registration country matches the code's `country` property.
10+
11+
A detailed scenario is provided later in the <<tax_resolution_example, Tax Resolution Example>> section.
12+
13+
== Getting Started with Aviate Tax
14+
15+
This section provides a step-by-step approach to get started with Aviate Tax.
16+
17+
=== Installing the Aviate Plugin
18+
19+
The Aviate plugin can be installed as documented in the https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html[How to Install the Aviate Plugin] doc.
20+
21+
=== Enabling Aviate Tax
22+
23+
To use the tax feature provided by the Aviate plugin, ensure that KB is started with the following property:
24+
25+
[source, bash]
26+
----
27+
com.killbill.billing.plugin.aviate.enableTax=true
28+
----
29+
30+
In addition, the Aviate Tax feature requires some tenant-level configuration. This can be done by executing the https://killbill.github.io/slate/tenant.html#add-a-per-tenant-configuration-for-a-plugin[per-tenant configuration] endpoint as follows:
31+
32+
[source, bash]
33+
----
34+
curl -v \
35+
-X POST \
36+
-u admin:password \
37+
-H 'X-Killbill-ApiKey: bob' \
38+
-H 'X-Killbill-ApiSecret: lazar' \
39+
-H 'X-Killbill-CreatedBy: admin' \
40+
-H 'Content-Type: text/plain' \
41+
-d '!!com.killbill.billing.plugin.aviate.AviateTenantConfig
42+
taxConfig:
43+
taxItemAmountPrecision: 2
44+
taxationTimeZone: UTC
45+
taxCodes:
46+
TAX_US_std_2000_19_6:
47+
description: VAT 19.6%
48+
rate: 0.196
49+
startingOn: 2000-04-01
50+
stoppingOn: 2014-01-01
51+
country: US
52+
TAX_US_std_2014_20_0:
53+
description: VAT 20%
54+
rate: 0.200
55+
startingOn: 2014-01-01
56+
stoppingOn: ""
57+
country: US
58+
products:
59+
Standard: TAX_US_std_2000_19_6, TAX_US_std_2014_20_0
60+
Sport: TAX_US_std_2000_19_6, TAX_US_std_2014_20_0' \
61+
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/aviate-plugin
62+
----
63+
64+
Here:
65+
66+
* `taxItemAmountPrecision` - Defines the number of decimal places to use when calculating and storing tax amounts.
67+
* `taxationTimeZone` - The timezone for tax.
68+
* `taxCodes` - This section defines the available tax codes and their attributes.Each tax code is uniquely identified (for example `TAX_US_std_2014_20_0`). The following attributes need to be specified for each tax code:
69+
** `description` - The tax code description. This is displayed in the tax invoice item.
70+
** `rate` - The tax percentage expressed as a decimal (e.g., 0.196 = 19.6%).
71+
** `startingOn` - Date on which the tax rate starts being applicable
72+
** `stoppingOn` - Date on which the tax rate stops being applicable
73+
** `country` - The ISO country code where the tax applies (e.g., `FR = France`).
74+
* `products` - Association between products and their tax codes. Must include each product to be taxed and a comma separated list of the applicable tax codes.
75+
76+
[[tax_resolution_example]]
77+
== Tax Resolution Example
78+
79+
To illustrate how Aviate Tax works, consider the following scenario:
80+
81+
Suppose the product called `Premium` has a 20% VAT rate in France. This rate is valid only after `2014-01-01`. Before that, from `2012-01-01` (included) to `2014-01-01` (excluded), a 19.6% VAT rate applied.
82+
83+
We can model this with two tax codes:
84+
85+
[source,yaml]
86+
----
87+
TAX_FR_std_2000_19_6:
88+
description: VAT 19.6%
89+
rate: 0.196
90+
startingOn: 2000-04-01
91+
stoppingOn: 2014-01-01
92+
country: FR
93+
94+
TAX_FR_std_2014_20_0:
95+
description: VAT 20%
96+
rate: 0.200
97+
startingOn: 2014-01-01
98+
stoppingOn: ""
99+
country: FR
100+
----
101+
102+
Notice that `TAX_FR_std_2014_20_0` does not have a `stoppingOn` date because it represents the current rate. When the VAT rate changes again, its `stoppingOn` must be set, and a new tax code must be defined with the updated rate.
103+
104+
Next, associate the tax codes with the product:
105+
106+
[source,yaml]
107+
----
108+
products:
109+
Premium: TAX_FR_std_2000_19_6, TAX_FR_std_2014_20_0
110+
----
111+
112+
This configuration states that the `Premium` product can be taxed with either the 19.6% or 20% VAT, depending on the applicable period.
113+
114+
**Example resolution:**
115+
116+
* If an invoice item covers the period `2013-12-01` → `2014-01-31`, the end date (`2014-01-31`) falls in 2014. Thus, the 20% rate (`TAX_FR_std_2014_20_0`) applies.
117+
* If an invoice item covers the period `2013-12-01` → `2013-12-31`, the end date (`2013-12-31`) falls in 2013. Thus, the 19.6% rate (`TAX_FR_std_2000_19_6`) applies.
118+
119+
Finally, the `country` property ensures that these tax codes apply **only** to accounts with `FR` set in `billingAccount#taxRegistration#address#country`. Accounts with no country or with a different country will not be taxed with these codes.
120+
121+
== Using Aviate Tax
122+
123+
Once the plugin is installed and tax support is enabled and configured, you can use it to automatically generate tax.
124+
125+
In brief, you would need to do the following:
126+
127+
1. Ensure that the aviate plugin is installed and the tax feature is enabled and configured as explained above.
128+
2. Create an account.
129+
3. Create a billing account corresponding to the account. Ensure that the billing account includes tax registrations with the appropriate country code in the address.
130+
4. Create a subscription corresponding to a product configured in Step 1. The tax invoice item will automatically be generated. See https://docs.killbill.io/latest/aviate-tax-tutorial.html[Aviate Tax Tutorial] for further details.

0 commit comments

Comments
 (0)