HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

The Avalara AvaTax connector for Optimizely Customized Commerce is an integrated transactional tax compliance tool for managing tax compliance obligations imposed by state, local, and other international taxing authorities. AvaTax applies US sales tax and VAT calculations as the transaction occurs via a secure, encrypted Internet connection, without disrupting your workflow.

## Requirements

  • No additional license fee for the add-on.

  • An Optimizely Commerce installation.

  • An [Avalara license and account](🔗).

  • See [Apps platform compatibility](🔗) for package and version information. 

## Install

The AvaTax Connector is installed with NuGet. You must install both the _Episerver.AvaTaxConnector_ and _Episerver.AvaTaxConnector.ConfigurationUI_.

  • Install through [NuGet](🔗).

  • Contact [Avalara](🔗) for configuration and setup.

## Documentation

  • [A Guide to US Sales Tax](🔗)

  • [Get Started: Avalara AvaTax Overview](🔗) (requires registration)

## Optimizely Customized Commerce AvaTax Connector

The AvaTax connector add-on is the Optimizely Customized 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.

### Build and package

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

### Configure

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


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.


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 Customized 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".

### AvataxConnector project structure

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.