Avalara Developer Network Developer avaTax

5.3 - Mapping Items to TaxCodes

Some customers prefer to go further - to actually create a product catalog and use AvaTax’s ItemCode feature to classify their products and link them with TaxCodes. Using this feature, it’s possible to build your connector or website without worrying about mapping products to TaxCodes at all.

This feature is entirely optional and is not required for certification of your AvaTax connector - but it may be useful if you prefer not to allow users to select tax codes in your product. Using Items, you can send your users directly to the AvaTax website and have them do their own data entry.

Here’s how it works.

  • AvaTax contains a database called the Item database. Any user of AvaTax can define a list of items using the CreateItems API or on the AvaTax website.
  • Each Item in the AvaTax database can be linked to a TaxCode or to custom TaxRule using a friendly web interface.
  • Your connector can simply identify each line on the invoice using an ItemCode in the CreateTransaction API call - AvaTax will look up its tax codes and tax rules for you.

You can read more about mapping items to tax codes on the Avalara Help Center.

Using the Items API

AvaTax includes a suite of APIs to manage your items database: for example, a good place to start is the CreateItems API. Here’s how to call the CreateItems API to create a single custom item - note that the API allows you to create as many items as you want with a single API call:

POST /api/v2/companies/1345/items
 
[
  {
   "companyId": 1345,
   "itemCode": "8987987",
   "taxCode": "DC010500",
   "description": "My Custom Item"
  }
]

Once you have created items, you can then use the ItemCode from each item in your CreateTransaction API call. AvaTax will lookup each item and use the corresponding tax code at the time of your CreateTransaction API call. This means that the user can visit the AvaTax website anytime and modify their item catalog - the changes will take effect without any code changes.

It’s worth mentioning that, if your business is part of the Streamlined Sales Tax (SST) program, you will be required to send both an ItemCode and Description for each product line on your orders. The Description is an SST requirement - it’s not listed as a required field for the API. Yet, sending a description is a best practice for all clients, not just those companies participating in SST program. In general, the Description field is used to specify additional details about the product, like a name, color, size, etc.