Last updated: Dec 02 2015

Episerver Commerce Avalara Connector

The Episerver Commerce AvaTax Connector provides functionality to calculate and document taxes with the Avalara AvaTax service.

Installation

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

Commerce Configuration

The Commerce installation must have fields on order forms to store AvaTax requests and responses.

To create order form meta-fields,

  1. Open the Commerce Manager UI.
  2. Select Administration > Order System > Meta Fields.
  3. Create two fields:
    1. Specify names indicating that they are for AvaTax requests and responses.
    2. Set the type to Long String
    3. Check Allow Null Values. Do not check any other options.
    4. Save the fields.
  4. Associate the fields with order forms:
    1. Select Order System > Meta Classes in the left menu.
    2. Select Element > Order Form.
    3. Select Type > Order Form Extended.
  5. Check the boxes next to the newly created fields in the field list, and click OK.

Order form data now has the necessary fields for integration with the AvaTax service.

You can customize the order system data further. If you want AvaTax integration for certain custom order form types, you can add the fields to those order form types.

Connector Configuration

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

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.
  • Tax Request Field Name and Tax Response Field Name. These must be set to the names of the fields created in the Commerce Configuration section, and determine where the most recent request and response is stored.
  • 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 configuration UI is intended to provide options that cover 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.

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