Kill Bill tax plugin for Avalara AvaTax and Avalara Tax Rates API.

This integration delegates computation of sales taxes to Avalara, which will appear directly on Kill Bill invoices.

Release builds are available on Maven Central with coordinates org.kill-bill.billing.plugin.java:avatax-plugin.

The plugin needs a database. The latest version of the schema can be found here.

The following properties are required:

• org.killbill.billing.plugin.avatax.url: AvaTax endpoint (e.g. https://development.avalara.net)
• org.killbill.billing.plugin.avatax.accountNumber: your AvaTax account number
• org.killbill.billing.plugin.avatax.licenseKey: your license key

The following properties are optional:

• org.killbill.billing.plugin.avatax.companyCode: your default company code (can be passed using the plugin property companyCode)
• org.killbill.billing.plugin.avatax.commitDocuments: whether invoices should be committed to Avalara

The following properties are required:

• org.killbill.billing.plugin.avatax.taxratesapi.url: Tax Rates API endpoint (e.g. https://taxrates.api.avalara.com)
• org.killbill.billing.plugin.avatax.taxratesapi.apiKey: your API Key

You can pass the rateType plugin property to specify which rate(s) to take into account.

For both APIs, the following properties are optional:

• org.killbill.billing.plugin.avatax.proxyHost: proxy host
• org.killbill.billing.plugin.avatax.proxyPort: proxy port
• org.killbill.billing.plugin.avatax.strictSSL: if false, unverified certificates are trusted

These properties can be specified globally via System Properties or on a per tenant basis:

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 'org.killbill.billing.plugin.avatax.url=XXX
org.killbill.billing.plugin.avatax.accountNumber=YYY
org.killbill.billing.plugin.avatax.licenseKey=ZZZ' \
     http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-avatax

Taxes are calculated using the address specified on the Kill Bill account. In case your current e-commerce application doesn't validate addresses, you can use Avalara's Address Validation service (a client implementation is provided by the plugin) to do it (Avalara will implicitly validate addresses during the tax calculation and fail the invoice creation if the address is invalid).

By default, Kill Bill will send Avalara all invoice line items: make sure to configure in the plugin the tax codes associated with your catalog products (see below).

Dry run invoices will contain a preview of the tax items (the associated document won't be committed to Avalara).

Here is how the main Avalara fields map to Kill Bill:

• Customer Code is mapped to the Kill Bill account external key if present, the account id otherwise
• Purchase Order No is mapped to the Kill Bill invoice id
• Line item code is mapped to the Kill Bill invoice item description, or the plan, phase or usage name (first non null)
• Line item Ref1 is mapped to the Kill Bill invoice item id
• Line item Ref2 is mapped to the Kill Bill invoice id

Documents in Avalara are not automatically voided (as this will depend on your dunning configuration). We do provide a client implementation though in case you want to cancel documents from your own plugin.

See also the AvaTax Rails mountable engine, which helps you administrate the plugin.

Set the customerUsageType custom field on the account object (e.g. E for charitable or benevolent organizations).

See Handling tax exempt customers for more details.

The plugin doesn't yet integrate with Avalara CertCapture to manage exemption certificates, but feel free to get in touch to see this feature added.

There are several ways to configure tax codes:

• For external charges, set the taxCode custom field on the invoice item object (e.g. PC040100 for general clothing products)
• For subscriptions, you can store the tax code for each product in your catalog 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: application/json' \
     -d '{"productName":"Super","taxCode":"DC010200"}' \
     http://127.0.0.1:8080/plugins/killbill-avatax/taxCodes

See What Is a Tax Code? for more details.