AvaTax connector installation and user guide

The AvaTax connector add-on is the Episerver Commerce connector for Avalara AvaTax, using Avalara address validation. The connector is available with the EPiServer.AvataxConnector NuGet package.

In this topic

Build and packaging

The sample site included in the repository creates a database with MSBuild instead of including a large binary in source control. Before you use it, you need to create databases by running MSBuild setup.targets. Databases instances are created to match the configured connection strings for EPiServerDB and EcfSqlConnection, which may be in a LocalDb or full SQL Server host.

You can create packages using the package spec files in the root of the repository. You must update the assembly version manually in the specification files, and build the AvataxConnector project with the Release configuration. The following commands create packages for distribution:

> nuget pack EPiServer.AvataxConnector.nuspec
> nuget pack EPiServer.AvataxConnector.ConfigurationUI.nuspec

Installing and configuring the AvaTax connector

Because taxes can be complex, contact Avalara for an account. They will engage Episerver Expert Services to configure AvaTax for your specific needs.

Customizing the AvaTax connector

Tax calculations require more data than is available in the stock commerce site, so the connector is extensible to support a wide range of use cases.

You can assign some values by basic configuration, such as:

  • Enter a business identification number directly in the configuration to send along with tax calculations.
  • Configure the tax code directly in the configuration for shipping charges. If you do not specify a value, the AvaTax connector uses the default tax code FR (freight).
  • Specify customer-level exemption numbers or entity/use codes in the configuration as the name of a field available on the Commerce customer object. If you do not specify these fields, an exemption number or entity/use code is not specified in tax calculations.
  • You can specify the item code and item tax code as fields names. The names must match properties on the catalog items being taxed.
  • You can configure the tax code for shipping charges.

In some cases, you may need more complex determination of tax document fields. The TaxDocumentFactory class lets you customize the tax document creation process.

You also can customize the address validation services by extending or replacing the AddressFactory class, which you must do for the Avalara address validation service to work with countries other than the US or Canada.

Usage

The AvataxManager class provides a central access point to AvaTax functionality. A typical Commerce site using AvaTax connector does the following:

  • Validate customer addresses with the ValidateAddressAsync method, and apply the results to an order address with the ApplyValidatedAddress method.
  • Calculate taxes with the CalculateTaxAsync, and apply the calculated result to an order with ApplyCalculatedTaxes.
  • Calculate taxes for a return (IReturnOrderForm) with the CalculateReturnTaxAsync method, the calculated results will be applied automatically to the return.
  • Cancel a tax document for an order/return with the CancelTaxAsync method.

Limitations

Address Validation

You need an address validation service, (but not specifically the Avalara address validation service) for certification with the AvaTax service. The Avalara address validation service only supports US and Canadian addresses, so you need a separate address validation service for use with other countries.

Configuration UI

The configuration UI is very bare-bones. It may be in need of some styling, and may be more user friendly if packaged and deployed as a shell module. It currently deploys source code directly into the front end site, within a MVC area named AvaTax.

Project Structure

AvataxConnector Project

The main project for the AvaTax connector. AvataxManager provides the main API for working with the AvaTax connector. The Models namespace contains the publicly accessible POCO model classes used by the connector. The Implementation namespace provides most of the underlying implementations, in classes injected via the service locator. These classes are organized to make it easy to extend or replace potions of the implementation to support specific user needs.

The persistent caching functionality was not removed completely, in case it proves necessary to use it for address validation to meet Avalara's requirements on limiting repeated requests. This should not be necessary, but it is easier to leave an unused class in the solution than to recreate it if it becomes necessary.

Build and common projects

These projects contain the build support to create the databases with setup.targets, and also functionality to share content between project (the contents of the Configs directory in the website and manager project are automatically copied from the common/Configs directory).

The common project also contains initialization modules to help automate the configuration of the test website.

Last updated: Nov 03, 2015