AvaTax tax compliance
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 with a secure, encrypted Internet connection, without disrupting your workflow.
Requirements
- No additional license fee for the add-on.
- An Optimizely Commerce installation.
- See Apps platform compatibilityApps platform compatibility for package and version information.
Install
The AvaTax Connector is installed with NuGet. You must install Episerver.AvaTaxConnector and Episerver.AvaTaxConnector.ConfigurationUI.
- Installed through NuGet.
- Contact Avalara for configuration and setup.
Documentation
- 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 in the repository creates a database with MSBuild instead of including a large binary in source control. Before you use it, you must create databases by running MSBuild setup.targets. Database 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 repository's root. 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.
📘 Note Contact Avalara for an account and support in setting up AvaTax.
The Service Configuration section contains details on configuring 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 must also 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, it 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 field's value 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 the tax code for shipping charges. If not set, the default value of FR is used.
The Customer Information Configuration section contains options for customer data integration.
- 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 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 are 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 need some styling and 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 through 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 is necessary to use it for address validation to meet Avalara's requirements for 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 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 projects (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.