This is an Aviate-only feature.

Introduction

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.

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.

A detailed scenario is provided later in the Tax Resolution Example section.

Getting Started with Aviate Tax

This section provides a step-by-step approach to get started with Aviate Tax.

Installing the Aviate Plugin

The Aviate plugin can be installed as documented in the How to Install the Aviate Plugin doc.

Enabling Aviate Tax

To use the tax feature provided by the Aviate plugin, ensure that KB is started with the following property:

com.killbill.billing.plugin.aviate.enableTax=true

In addition, the Aviate Tax feature requires some tenant-level configuration. This can be done by executing the per-tenant configuration endpoint as follows:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d '!!com.killbill.billing.plugin.aviate.AviateTenantConfig
  taxConfig:
  taxItemAmountPrecision: 2
  taxationTimeZone: UTC
   taxCodes:
    TAX_US_std_2000_19_6:
      description: VAT 19.6%
      rate: 0.196
      startingOn: 2000-04-01
      stoppingOn: 2014-01-01
      country: US
    TAX_US_std_2014_20_0:
      description: VAT 20%
      rate: 0.200
      startingOn: 2014-01-01
      stoppingOn: ""
      country: US
  products:
    Standard: TAX_US_std_2000_19_6, TAX_US_std_2014_20_0
    Sport: TAX_US_std_2000_19_6, TAX_US_std_2014_20_0' \
    http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/aviate-plugin

Here:

  • taxItemAmountPrecision - Defines the number of decimal places to use when calculating and storing tax amounts.

  • taxationTimeZone - The timezone for tax.

  • 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:

    • description - The tax code description. This is displayed in the tax invoice item.

    • rate - The tax percentage expressed as a decimal (e.g., 0.196 = 19.6%).

    • startingOn - Date on which the tax rate starts being applicable

    • stoppingOn - Date on which the tax rate stops being applicable

    • country - The ISO country code where the tax applies (e.g., FR = France).

  • 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.

Tax Resolution Example

To illustrate how Aviate Tax works, consider the following scenario:

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.

We can model this with two tax codes:

TAX_FR_std_2000_19_6:
  description: VAT 19.6%
  rate: 0.196
  startingOn: 2000-04-01
  stoppingOn: 2014-01-01
  country: FR

TAX_FR_std_2014_20_0:
  description: VAT 20%
  rate: 0.200
  startingOn: 2014-01-01
  stoppingOn: ""
  country: FR

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.

Next, associate the tax codes with the product:

products:
  Premium: TAX_FR_std_2000_19_6, TAX_FR_std_2014_20_0

This configuration states that the Premium product can be taxed with either the 19.6% or 20% VAT, depending on the applicable period.

Example resolution:

  • 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.

  • 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.

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.

Using Aviate Tax

Once the plugin is installed and tax support is enabled and configured, you can use it to automatically generate tax.

In brief, you would need to do the following:

  1. Ensure that the aviate plugin is installed and the tax feature is enabled and configured as explained above.

  2. Create an account.

  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.

  4. Create a subscription corresponding to a product configured in Step 1. The tax invoice item will automatically be generated. See Aviate Tax Tutorial for further details.