Episerver Commerce AvaTax Connector

The AvaTax connector add-on is the Episerver Commerce connector for Avalara AvaTax, using Avalara address validation. The AvaTax connector provides functionality to calculate and document taxes with the Avalara AvaTax service. 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

Installation

The AvaTax Connector is installed with NuGet. You must install both the Episerver.AvaTaxConnector and Episerver.AvaTaxConnector.ConfigurationUI.

Configuration

Configure the connector in the Episerver edit view, by selecting AvaTax from the top-level menu.

Note: Contact Avalara for an account and support in setting up AvaTax.

The Service Configuration section contains details to configure your Avalara account.

  • Account Number. The Avalara account number.
  • License Key. The Avalara license key (password).
  • Company Code. The Avalara company code.
  • Service URL. You can set this to use a custom service URL. In most cases, this should be left blank. If enabled, the Use Production Service setting is ignored.
  • Use Production Service. If enabled, the production Avalara service is used. If disabled, the development service is used.
  • Enable Logging. Enable to include additional logging of transactions to the Avalara web services. If enabled, the Episerver logging configuration also must be configured to permit information messages from the Episerver.AvaTaxConnector.AvaTaxManager type.
  • Request Timeout. This value is used as the request timeout for transactions with the AvaTax service, and is specified in milliseconds.

The Tax Document Configuration section contains options for the creation of tax documents.

  • Disable Document Committing. If enabled, prevents the connector from committing tax documents.
  • Disable Tax Calculation. Prevents the connector from calculating taxes if checked.
  • Business Identification Number. If specified, this is added as a document-level business identification number to all tax documents.
  • Item Code Field. If set, this must be the name of a meta-field on catalog entry objects. The value of this field is used as the item identifier in tax documents. If this is not set, the Catalog Entry Code is used as the default.
  • Item Tax Code Field. If set, this must be the name of a meta-field on catalog entry objects. The value of the field is used as the tax code for the catalog entry.
  • Default Item Tax Code. If a tax code for a catalog item cannot be determined with the Item Tax Code Field setting, then the Default Item Tax Code value is used.
  • Shipment Tax Code. This is used as the tax code for shipping charges. If not set, the default value of FR is used.

The Customer Information Configuration section contains options for integrating with customer data.

  • Customer Code Field. If set, this must be the name of a meta-field on the Customer object. The value of this field is sent to Avalara as the customer identifier. If not set, the primary key value of the customer is used.
  • Exemption Number Field. If set, this must be the name of a meta-field on the Customer object. The value of this field is sent to Avalara as an exemption code.
  • Entity/Use Code Field. If set, this must be the name of a meta-field on the Customer object. The value of this field is sent to Avalara as an entity/use code.

Advanced Configuration

While the basic configuration covers most normal usages of the connector, you can further customize the creation of tax documents by overriding the implementation of the Episerver.AvaTaxConnector.Implementation.TaxDocumentFactory class, and injecting the customized implementation into the Service locator.

The TaxDocumentFactory class has a separate method for each field in the tax document. 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.

Note: Make sure your customized workflow activities use calculators. That allows your commerce system access to the AvaTax connector automatically.

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 an 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: Dec 02, 2015