Avalara Developer Network Developer avaTax

5.1 - Finding a Tax Code

So far in the developer guide, your code has left the taxCode field empty. In this case, AvaTax assumes you are creating transactions that refer to general Tangible Personal Property, which is represented by the default tax code P0000000.

As long as you continue using a null tax code, AvaTax will treat your products the same. However, many products are taxed differently in different jurisdictions. Finding the correct tax code will ensure that AvaTax treats your product correctly everywhere.

You can find the correct tax code for your product in one of two ways:

When you use tax codes correctly in AvaTax, you will get the correct tax rate for your transaction. Some customers will choose to enter a tax code directly when creating a transaction.

Other customers may wish to search for tax codes directly through the ListTaxCodes API. A common use case is to show a drop down text box. When a customer starts typing the word C, your program can call ListTaxCodes to find all tax codes that begin with the letters that the customer has typed. Here’s how to call ListTaxCodes:

GET /api/v2/definitions/taxcodes/$filter=description startswith C
 
{
  "id": 56789,
  "companyId": 12345,
  "taxCode": "PF050101",
  "taxCodeTypeId": "P",
  "description": "Carbonated beverages",
  "parentTaxCode": "PF050001",
  "isPhysical": true,
  "goodsServiceCode": 0,
  "entityUseCode": "",
  "isActive": true,
  "isSSTCertified": true
}

Adding TaxCodes to your Transaction

On the document line level you can pass via the CreateTransactionModel. There are a few properties that allow you to identify your line categories of ItemCode, Quantity, Amount, Description, and TaxCode. The ItemCode are generally the value passed by your integration or web service to represent a part number, SKU or product ID for the said products or services.

Here’s what a transaction looks like when you add tax codes to a line:

Test Case - 5.1.1

Setup

  • Carbonated Beverages are considered exempt in Washington State.
  • The TaxCode for a Carbonated Beverage is PF050101.
  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-5-Test-1
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
    • Addresses:
      • SingleLocation
      • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
    • Line #1:
      • Amount 100
      • TaxCode PH405370 (gift items)
  • Calculate tax for your transaction using AvaTax.

Assertions

  • The tax for line 1 should be $9.00.
  • The Taxable amount for line 1 should be $100.00.
  • {
      "type": "SalesInvoice",
      "code": "Chapter-5-Test-1",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "PH405370"
        }
      ]
    }
                    

As you can see, this transaction now has different taxability rules based on the type of product being sold.