Configuring the 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:

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

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.

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.