Avalara AvaTax

Avalara is an American cloud-based sales tax and compliance provider.

Avalara is a one of only six Certified Service Providers available to retailers in the United States, delivering them from the responsibility of trying to work out how much tax they owe to which authority (Figure 1.1).

Figure 1.1 An example of taxes provided by Avalara AvaTax in Dynamicweb

Avalara AvaTax is therefore a US domestic service only.

To integrate with Avalara AvaTax, you must:

  • Have a valid Avalara AvaTax account
  • Ensure that your orders have the correct address details when created – we recommend using the Avalara Address validation service to verify user input

In this document, we will go over the basic process of integrating with Avalara AvaTax from within Dynamicweb. To learn more about Avalara AvaTax, please refer to the Avalara website.

Be aware that:

  • Dynamicweb does not integrate to AvaTax Cert.
  • You should not use VAT and the Avalara AvaTax provider together
  • Although the integration is able to handle returns and invoices, shipping taxes and shipping discounts are currently not supported for those operations
  • AvaTax cannot handle discounts on a product level (orderline discounts), so Dynamicweb applies any discounts to the product before sending it to Avalara. Discounts applying to the entire order (order discounts) are registered together, as total discount, in AvaTax.

To obtain a test account, contact you Dynamicweb Software A/S partner – or go to the Avalara website and create one on your own.

To get started with the Avalara AvaTax provider, you must register a sandbox account for testing purposes (or you can use your existing account, if you have one).

On creation, you can log in to the Avalara Admin Console and go through the registration process to obtain your test credentials:

  • An account name
  • An account number
  • A license key
  • A webservice URL

You must also create your company in the Avalara backend, and create a unique company code for it (Figure 2.1).

You will use these credentials to configure the Avalara AvaTax provider in Dynamicweb.

Figure 2.1 The company settings in the AvaTax interface

Why do all my transactions show us as non-taxable?!?
Don’t forget to set up Nexus Jurisdictions for your company in the AvaTax interface, or all your transactions will be registered as non-taxable. This includes selecting the states in which you do business, and any local jurisdictions (County, City & Special Tax Jurisdictions) in those states. Read more about Nexus jurisdictions.

Once you’ve obtained your Avalara credentials, you must create and configure an Avalara AvaTax tax method in Dynamicweb.

To do so:

  • Create or edit a Tax method in the Settings > Ecommerce > Product Catalog > Taxes following the regular procedure
  • Select the Avalara tax provider from the dropdown menu
  • Fill in the necessary parameters (Figure 3.1)
Figure 3.1 The Avalara AvaTax tax provider settings

You must:

  • Enter your account number, license key, company code and webservice url (https://sandbox-rest.avatax.com/ for testing and https://rest.avatax.com for production)
  • Enter the details about the address from where the goods are shipped (this impacts some tax-aspects)
  • Select your validation boundary level - Address, Zip5, or Zip9
  • Select from where you want to retrieve the customer code sent to AvaTax - AccessUserID, CustomerNumber, or the ExternalID field of the user identified by the AccessUserID. This gives you full flexibility as to decide where to store the customer number that is sent to Avalara.

You can also check the following:

  • Enable commit commits the transactions in AvaTax - if unchecked, the final commit call is not sent by Dynamicweb to AvaTax, allowing shop administrators to have another system (e.g. an ERP) make the final tax commitment – until then, all transactions (sales, returns and invoices) are registered as uncommitted in AvaTax.
  • Do not use in product catalog disables rendering taxes from AvaTax in the product catalog. This will improve performance.
  • Don't calculate taxes if (Exemption number) is set disables taxes for users with any value in the system field ExemptionNumber - this field is generated on each user when an AvaTax provider is created.
  • Debug logs requests and responses from Avalara AvaTax - the logfile is located in System/Log

Customer numbers from custom fields

If you have a non-standard place where the customer number is stored (such as a custom field on the user), you can use the NotificationManager API to provide your own value. Subscribe to the Dynamicweb.Ecommerce.TaxProviders.AvalaraTaxProvider.AvalaraTaxProvider.OnGetCustomerCode notification and return the customer code in the CustomerCode property of the NotificationArgs argument of OnNotify.

Once you’ve configured the tax provider, you can use the test connection button (Figure 4.1) to – well – test your connection.

Figure 4.1 Testing your connection

Testing the connection returns a result (e.g. success) and a list of operations tested, as well as the license key expiration date.

Apart from testing the connection, you should of course also test your setup thoroughly to verify that everything performs as intended and expected. 

The TaxProviderErrors loop renders any technical or incorrect setting errors, that are can happened during the tax rate calculation service requests. If any error is present, the tax is not calculated (equal to 0) and the order can’t be passed to the checkout step, because it doesn’t pass pre-checkout validation.

Once you are ready to go live, simply:

  • Exchange your test credentials with your production credentials (from your non-sandbox account)
  • Exchange the development URL with the production URL: https://avatax.avalara.net

AvaTax depends on two custom product fields – Item Code and Tax Code (Figure 6.1) – which are created automatically when using the Avalara AvaTax Provider. They are used to define special product taxability rules:

  • The Item Code is used to identify each unique item (product, service or charge)
  • The Tax Code is a code used to link groups of items together, e.g. for creating Tax Rules for custom taxing scenarios.
Figure 6.1 Custom fields required by Avalara AvaTax

Please DO NOT DELETE these custom product fields – although they will be recreated by the Avalara AvaTax provider, it may lead to taxation errors for products already added to the shopping cart.

You can read more about item codes and tax codes in the Avalara documentation.

If an order is created and completed by an anonymous user, the user will be assigned 0 as the Cust/Vendor Code in AvaTax. Logged-in users will be assigned a Cust/Vendor Code matching their User ID.

When using the tax provider, two system fields will be created on users:

  • An ExemptionNumber field
  • An EntityUseCode field

These fields allow you to exempt users from paying tax, if their status (e.g. as foreign diplomats) affords them that privilege.

Read more about exempting users from sales tax in the Avalara documentation.

Orders from Dynamicweb are created with the Doc Type Sales Invoice in AvaTax. Completed orders are registered as Doc Type Committed in AvaTax, unless the do not commit checkbox has been checked in the tax provider settings, in which case the order is registered as uncommitted. Orders cancelled in Dynamicweb are registered as voided in AvaTax.

If an order is edited in Dynamicweb, the order is also changes in AvaTax. It will be shown with an adjusted document icon in the Avatax backend, and a reason – price/quantity adjusted – and a description; order was edited in backend.

Edited order lines are automatically recalculated in AvaTax to match the Dynamicweb order (which is also updated with the new tax calculation).

Return orders created from an RMA with refund as the RMA action are created in AvaTax as Return Invoice doc types. The other RMA types (defective or exchange) create orders with a total of 0 and are not processed in AvaTax.