Configuring the Plugin · Elastic Path Commerce Avalara Plugin

Plugin Configuration

The Avalara plugin is configured using the plugins.json mechanism provided by the Extension Point Framework.

A sample plugins.json file for the Avalara plugin is shown below:

{
    "plugins": [
       {
          "identifier": {
             "pluginId": "elasticpath-avalarataxcalculatorplugin-*"
          },
          "settings": [
             {
                "key": "AVALARA_URL",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.url}"
                   }
                ]
             },
             {
                "key": "AVALARA_ACCOUNT",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.account}"
                   }
                ]
             },
             {
                "key": "AVALARA_LICENSE",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.license}"
                   }
                ]
             },
             {
                "key": "AVALARA_COMPANY_CODE",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.company.code}"
                   }
                ]
             },
             {
                "key": "HASH_ITEM_CODE",
                "dataType": "BOOLEAN",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": false
                   }
                ]
             },
             {
                "key": "TAX_CODE_MAP",
                "dataType": "SHORT_TEXT",
                "collectionType": "MAP",
                "values": [
                   {
                      "key": "GOODS",
                      "value": "PP198874"
                   },
                   {
                      "key": "DIGITAL",
                      "value": "DC010500"
                   },
                   {
                      "key": "SERVICE",
                      "value": "SS020000"
                   }
                ]
             }
          ]
       }
    ]
}

The setting fields supported by the Avalara plugin are described below. A setting whose description begins with Optional can be left out of plugins.json. The others are required.

Setting Key	Description	Example
AVALARA_URL	The URL of the REST API endpoint provided by Avalara. For test environments, set this to `https://sandbox-rest.avatax.com`. For production environments, set this to `https://rest.avatax.com`. For more information see "What are the service URLs for AvaTax calculation services?". Note that the plugin automatically appends the `/api/v2` path to the URL.	`https://sandbox-rest.avatax.com`
AVALARA_ACCOUNT	Your account number defined by Avalara.	`1100119159`
AVALARA_LICENSE	Your license code defined by Avalara.	`123A456B789C0912`
AVALARA_COMPANY_CODE	Your company code defined by Avalara.	`COMPANY_CODE`
HASH_ITEM_CODE	A boolean value indicating whether product sku codes should be hashed. Avalara supports a maximum of 50 characters in the item code identifier field. If your product sku codes are longer than 50 characters, set this to true so that the plugin will hash the product sku codes to a shorter value.	`false`
SOCKET_TIMEOUT	Optional. How long, in milliseconds, the plugin waits for a response from Avalara. Defaults to `10000`. Use the `INTEGER` data type.	`10000`
CONNECT_TIMEOUT	Optional. How long, in milliseconds, the plugin waits to open a connection to Avalara. Defaults to `5000`. Use the `INTEGER` data type.	`5000`
TAX_CACHE_TIME_TO_LIVE	Optional. How long, in seconds, a calculated tax result is retained in the plugin's cache. Defaults to `600`. Values of zero or less are ignored. Use the `INTEGER` data type.	`600`
TAX_CACHE_TIME_TO_IDLE	Optional. How long, in seconds, an unused tax result is retained in the plugin's cache. Defaults to `600`. Values of zero or less are ignored. Use the `INTEGER` data type.	`600`
TAX_CACHE_MAX_OBJECTS	Optional. How many tax results the plugin's cache retains. Defaults to `5000`. Values of zero or less are ignored. Read Tax Calculation Cache before raising this. Use the `INTEGER` data type.	`5000`
TAX_CODE_MAP	Optional. A map of key/value pairs that can be used to convert the tax codes defined on products in Elastic Path Commerce to the tax codes required by Avalara. If an entry is not found in the map for a tax code defined in Elastic Path Commerce, it will be sent to Avalara as-is. Use the Avalara Tax Codes Search to find the tax codes that Avalara supports.	See sample JSON above.

Per-Store Configuration

Each Elastic Path store can file taxes under its own Avalara company. To do this, override AVALARA_COMPANY_CODE per store using the extensions.json mechanism provided by the Extension Point Framework. The TAX_CODE_MAP setting can be overridden the same way.

These two settings are the only ones you can override per store. The rest are read from plugins.json only, and are ignored if you declare them in extensions.json. All stores share a single Avalara client, so the credentials and the timeout settings cannot vary by store.

Each of the two settings falls back on its own:

An entry that declares only AVALARA_COMPANY_CODE uses that code with the TAX_CODE_MAP from plugins.json.
An entry that declares only TAX_CODE_MAP uses that map with the AVALARA_COMPANY_CODE from plugins.json.
An entry that declares neither uses the plugins.json values for both.

Keep AVALARA_COMPANY_CODE in plugins.json even if every store overrides it. The plugin does not start without it.

The following example gives the STORE_CA store its own company code, and serves every other store from a catch-all entry:

{
    "extensions": [
       {
          "identifier": {
             "pluginId": "elasticpath-avalarataxcalculatorplugin-*",
             "extensionClass": "com.elasticpath.plugins.avalara.extension.AvalaraTaxCalculator",
             "extensionPointKey": "TAX_CALCULATOR"
          },
          "enabled": true,
          "priority": 100,
          "defaultSelectorMode": "DEFAULT_NONE",
          "selectors": [
             {
                "type": "XPFExtensionSelectorByStoreCode",
                "value": "STORE_CA"
             }
          ],
          "settings": [
             {
                "key": "AVALARA_COMPANY_CODE",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.ca.company.code}"
                   }
                ]
             }
          ]
       },
       {
          "identifier": {
             "pluginId": "elasticpath-avalarataxcalculatorplugin-*",
             "extensionClass": "com.elasticpath.plugins.avalara.extension.AvalaraTaxCalculator",
             "extensionPointKey": "TAX_CALCULATOR"
          },
          "enabled": true,
          "priority": 200,
          "defaultSelectorMode": "DEFAULT_ALL",
          "settings": [
             {
                "key": "AVALARA_COMPANY_CODE",
                "dataType": "SHORT_TEXT",
                "collectionType": "SINGLE",
                "values": [
                   {
                      "value": "${avalara.company.code}"
                   }
                ]
             }
          ]
       }
    ]
}

Each entry creates its own instance of the tax calculator. The Extension Point Framework selects the instance by store code for tax calculation, commit and delete alike. An order is therefore committed under the same company code that quoted it.

For the general mechanics, see Selectors. Four points matter when you configure this plugin:

Declaring any extensions.json entry for the Avalara tax calculator replaces the assignment that the plugin makes on its own. Stores that no entry matches fall through to the built-in ElasticPathTaxCalculator, which uses the tax rates configured in Commerce Manager. The catch-all entry in the example prevents this.
Give the catch-all entry a higher priority number than the store-specific entries. The Tax Calculator extension point invokes a single extension, and the lowest priority number wins.
Keep every Avalara entry below 1010, which is the priority of ElasticPathTaxCalculator.

note

Setting fields accept two spellings. This page uses key and values. The Extension Point Framework documentation uses settingKey and settingValues. Both work.

Tax Calculation Cache

The plugin caches tax results, so that repeated calculations for the same tax problem do not each become a call to Avalara. A cached result is reused only when every value that the plugin sends to Avalara is unchanged. The cache cannot serve one shopper's tax to another, and it cannot reuse a result across a change of address, cart contents or calendar day.

The TAX_CACHE_TIME_TO_LIVE, TAX_CACHE_TIME_TO_IDLE and TAX_CACHE_MAX_OBJECTS settings size this cache. Three things are worth knowing before you change them:

The cache is held on the heap and is local to each application node. Raising TAX_CACHE_MAX_OBJECTS increases memory use on every node running the plugin. A deployment behind a load balancer without session affinity holds a separate copy per node.
Each extension instance holds its own cache. A deployment with several store-specific entries therefore holds several caches on each node.
The settings are read when the plugin starts, so a change takes effect when the plugin is reloaded rather than immediately.

If the Avalara call volume is higher than you expect, check the cache first. An entry that is evicted because TAX_CACHE_MAX_OBJECTS has been reached becomes a fresh Avalara call on the next request for that cart.

Tax Jurisdiction Configuration

In order to calculate taxes through Avalara, Elastic Path needs to know if the country requires that taxes be included in the price of the purchase (inclusive taxes), or separately from the price of the purchase (exclusive taxes). This flag needs to be passed to Avalara so it can calculate taxes correctly.

To define if a region is tax inclusive or exclusive, a tax jurisdiction record needs to be created. To create a tax jurisdiction in Commerce Manager, click the "Configuration" option at the top of the page, and then select "Tax Jurisdictions" from the left-hand menu bar.

Tax Jurisdiction Configuration

Since Avalara is calculating the rates, you do not need to add any taxes to the list. Just set the country and tax calculation method.

If a shopper enters an address for which there is no tax jurisdiction record, a warning will be logged and the Elastic Path will assume that the tax calculation method is "exclusive".

Product Configuration

Make sure to define the appropriate tax code for each product in your catalog. To determine the correct tax code, refer to the Avalara Tax Codes Search. If you are using the tax code map setting, then your internal codes may be different from the Avalara tax codes.