How do you know if you’re compliant with our best practices? To start, we recommend watching an overview of our API.
An integration can be issued for any of the following feature subsets in addition to a basic calculation certification:
To have your integration Certified by Avalara, we have outlined the areas of integration that are necessary to ensure a stable and robust customer experience using AvaTax with your application. To be Certified for Avalara AvaTax, all of the items with an R beside them listed below are the required elements that must be present in your integration.
Note: Address validation is a requirement for certification, however we don’t require you to use our address validation service.
There are several different certifications that can be achieved according to the functionality supported in your application.
The AvaTax Administration section provides the user with configuration, setup and utility functions necessary to administer the AvaTax sales tax calculation and address validation functions. Note that these items cannot be examined on a analysis of your data performed by AvaTax support staff.
Here’s a video showing an example of one of our integrations to AvaTax and how a configuration screen should be designed:
AvaTax Configuration – dialog window
The AvaTax Configuration Dialog window must allow the user to specify the configuration/connection information.
Tests the connection to the AvaTax service and verifies the AvaTax credentials. This is an important element to allow for successful troubleshooting of the AvaTax service. Optional – display license key expiration date upon successful connection response.
Control – Disable Document Committing
In order for this connector to be used in conjunction with other integration to AvaTax, the user must be able to control which connector is used for committing documents to AvaTax. From a technical standpoint, simply use DocType = SalesOrder on all calls and suppress any non-getTax calls (i.e. cancelTax, postTax).
Tax Calculation – Disable tax calculation option
The user must have an option to turn on or off the AvaTax Calculation service independent of any other Avalara product or service.
User Implementation Guide
The User Implementation Guide should contain screenshots and information allowing the end user to configure for AvaTax including where the company code is entered, where the credentials are entered and where tax codes can be mapped within the application.
Enables detailed AvaTax transaction logging within the application including capture of round-trip processing time.We need the complete xml request/response for each call made to Avalara services. It does not need to run all the time as we understand the DB will grow unnecessarily large – you are free to only log the last week, 30 days, custom, or have a control for the next N hours, etc. The spirit of the requirement is to assist customers and support in troubleshooting exercises, so it needs to be retrievable by an end user (or an administrator) It should be specifically Avalara service calls.
Request time out definition
Define AvaTax request time out length, AvaTax best practices prescribes default setting of 300 ms.
Here’s a video showing an example of the required elements of the customer record integration to AvaTax:
Identify customer code (number, ID) to pass to the AvaTax service.
Customer record field populating exemption number in an AvaTax transaction. This is used for tracking those customers who have tax exempt transactions.
This is a group of codes that indicate the type of exemption. See the standard codes, but be aware that users are able to create custom codes as well.It is best to manage this value in your application’s Customer record and pass it to AvaTax as CustomerUsageType at either the document or line level, whichever is applicable. Note that either Exemption Number or Entity/Use code is required (not both). Entity/Use Code is preferred.
Here’s a video showing an example of the item record elements necessary for a successful integration to AvaTax:
Identify item/service/charge code (number, ID) to pass to the AvaTax service. If the customer has access to UPC, they should be able to prepend UPC to the code and have it come across in the item code field. If there is no UPC, it should fall back to SKU.
Identify item/service/charge description to pass to the AvaTax service with a human-readable description or item name.
AvaTax tax code mapping – Item Code/SKU
Association of an item or item group to an AvaTax Tax Code to describe the taxability group (e.g. Clothing-Shirts – B-to-C). If possible, this should be assigned at the item category level as well as the item level.
Sales/Billing Document Integration
Integrating with the Sales and/or Billing process involves making tax calculation and/or modifying a transaction. Here’s a video showing an example of all necessary elements for a successful integration to AvaTax:
Send required header level data elements:
Tax calculation date
Entity/Use code (aka CustomerUsageType)
Note that Exemption number or Entity Use Code should be passed only if the customer is exempt.
Send required line (detail) level data elements:
Freight Items must be transmitted separately
Freight Items must be sent to AvaTax as a separate line item with appropriate tax code.
GetTax call – Sales Order/Sales Invoices
Ensure that invoices are processed through a logical document lifecycle.
PostTax/CommitTax call – Invoices
Ensure that invoices are committed/posted for reporting appropriately.
PostTax/CommitTax call – Credit Memos
Ensure that returns are committed/posted for reporting appropriately. More details about handling returns.
CancelTax call – voided/deleted Invoices
When invoices are deleted/cancelled, this information must be transmitted to AvaTax.
CancelTax call – voided/deleted Credit Memos
When returns are deleted/cancelled, this information must be transmitted to AvaTax.
Send original invoice date as tax calculation date for return orders/credit memos
Any tool or utility that allows the user to query or retrieve already recorded transaction records for the purpose of reconciling with the document records in the application. Should not trigger a recalculation of tax by default (although may do so on demand). No GetTaxHistory or document retrieval method is yet available in the REST API.
GetTaxHistory – Credit memo inquiry
No GetTaxHistory or document retrieval method is yet available in the REST API.
Server Audit Clarity and Installation Requirements
Tax calculation should display a clean audit to promote an error- and overage-free user experience. These properties are not visible from the Admin Console, and show up on an Avatax-side server audit of traffic on your account. Contact us if you would like an audit report run and emailed to you.
Pass connector identifier information via the TaxSvc.Profile.Client property
Integrations must include information about the connector, such as name, version, and company name, as a signature to each transaction. EXAMPLE: TaxSvc.Profile.Client = “Dynamics AX,9.0,MyApp for AX by ACME INC,1.0”
Reasonable errors on server-side analysis
There should be no errors except those that would result from normal (but invalid) user input (e.g. invalid address data). Such errors must be logged/displayed appropriately to the application.
Reasonable ratio of GetTax and address validation calls to committed documents
In a normal workflow, we expect to see (on average, including abandoned carts) up to 10 tax calculations per finalized document. In a straight-forward order entry process, the number of calls should be about three to five.
Demonstrate and document installation of software – Install Shield or equivalent where applicable
Customers should have an easy and trouble free installation of the software.