Getting a tax calculation is the primary reason developers use the Avalara AvaTax Service. Whether you are just looking to get a tax rate to populate into a database or application field, or you need to utilize all of the reporting and filing functionality that AvaTax offers, CreateTransaction is the starting point.

The request for this method consists of sales document attributes, like date, customer id, addresses, and line items. Please see the API reference for a full listing of the available operations and attributes.

ItemCode, Description, and TaxCode

On the document lines that you will pass to us in the CreateTransactionRequest, there are a few properties that allow you to identify your products or product categories - ItemCode, Description, and TaxCode.

ItemCode is typically a SKU or other product ID, and usually represents individual products or services.

The Line Description is a string that will elaborate more details about the product, such as name, color, size, etc.

Note: If you are working within the constraints of the Streamlined Sales Tax (SST) program, you are required to provide both an ItemCode and Description for each product line on your orders. As such, we consider this to be the best practice for all clients, including those not currently participating in SST.

The other product property you need to make note of on document lines is TaxCode. Avalara provides a set of AvaTax System Tax Codes that you can apply to your items. Your selections from this list of tax codes can be passed in the TaxCode property of each Line to allocate that product to a particular taxability category. This is generally the best practice if you can manage TaxCodes in your application.

As an alternative, you may map items to tax codes in the AvaTax Website if you have no way to do that in your application. If you do this, you only need to send the ItemCode in your request since it will already be associated with a TaxCode in the AvaTax Website. However, there is a drawback. This will introduce an extra step into the item maintenance process when new items are added to your catalog and could get out of synch if the user isn’t diligent to maintain the relationship.

If both of these options are used, the AvaTax Website mapping takes precedence.

Shipping and Freight

We expect to see freight charges passed to AvaTax just like any other charge – as an additional line item. You can populate the TaxCode property of the Line object with an AvaTax System Tax Code like FR020100, or just FR for AvaTax Basic subscribers, to classify the item as a freight charge. This tax code will allow AvaTax to calculate tax on freight according to the regulations of the state referenced in the Destination or Ship-to address.