Avalara Developer Network Developer avaTax

11.3 - Tax Content API

The Tax Content API Response

Avalara’s Tax Content API provides businesses with the content required to calculate tax locally in a disconnected environment. The Content API response includes tax jurisdiction, tax rate, and product/service taxability information for each Tax Code and storefront Location configured in your AvaTax account. To begin, let’s take a look at the fields included in a Tax Content API response.

Here are the details for each field included in a Tax Content API response:

ScenarioId Field Description Sample Data
ScenarioId This field is used to group tax scenarios together. A tax scenario will consist of a single Location and single Tax Code 1
EffDate The date the tax information becomes effective 4/1/2011 12:00:00 AM
EndDate The date the tax information is no longer effective. Tax data is effective on this date, but is not effective on the following date 12/31/9999 12:00:00 AM
LocationCode Unique location identifier 001
TaxCode Avalara System Tax Code or Custom Tax Code P0000000
ShipToCity The ship-to city Durham
ShipToCounty The ship-to county DURHAM
ShipToState The ship-to state NC
ShipToPostalCode Postal code associated with the location address 27707-1764
ShipToCountry The ship-to country US
JurisType The jurisdiction type. There are five supported values - Country, State, County, City, Special State
JurisCode Unique numeric, alpha, or alphanumeric code identifying a jurisdiction. This field is optional 001, EKTF0
JurisName The name of the jurisdiction that corresponds to this tax record NORTH CAROLINA
TaxType The tax type associated with the rate Sales
Tax_Description The description of the tax NC STATE TAX
Tax_Rate The tax rate. "0.03" corresponds to 3%. Exempt records will have a rate of 0. 0.03
Cap Applies a cap to the taxable amount. Amounts up to the cap are taxable. Amounts over the cap are non-taxable. The tax rate applies to the taxable amount. 0
Threshold Applies a threshold to the taxable amount. Amounts up to and including the threshold are non-taxable. Amounts over the threshold are taxable. The tax rate applies to the taxable amount. 100
TaxRuleOptions Applies a special tax scenario rule to the transaction. There is only one supported value at this time: TaxAll. With a threshold, this rule taxes the entire amount once the total reaches the threshold TaxAll
TaxApplicationLevel This field is not used at this time, but will be leveraged for tax-on-tax scenarios in the future. This field will define the order in which taxes are applied in a tax-on-tax scenario and the tax base for each individual tax N/A


Consuming Tax Content

In order to calculate tax locally, you’ll need to implement logic in your native POS application that can correctly interpret and calculate tax using the data from the Tax Content API. The next sections will review common uses cases for leveraging the Tax Content API results to calculate tax locally.

Thresholds & Caps

This section is about interpreting Cap & Threshold values included in Tax Content API results. By the end of this section, you will learn the following

  • How to interpret Threshold and Cap values
  • How to interpret TaxRule Options associated with Cap and Threshold values

Thresholds

Assertions

Address: 82 Smith St, Providence, RI 02903-1105
Tax Code(s): PC040100

Expected API Result
[
  {
      "ScenarioId": 1,
      "EffDate": "12/1/2013 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "RI001",
      "TaxCode": "PC040100",
      "ShipToCity": "Providence",
      "ShipToCounty": "PROVIDENCE",
      "ShipToState": "RI",
      "ShipToPostalCode": "02903-1105",
      "ShipToCountry": "US",
      "JurisType": "State",
      "JurisName": "RHODE ISLAND",
      "TaxType": "Sales",
      "Tax_Description": "RI STATE TAX",
      "Tax_Rate": 0.07,
      "Cap": "0",
      "Threshold": "250.000000",
      "TaxRuleOptions": "",
      "TaxApplicationLevel": ""
  }
]


As noted in Chapter 1, the Threshold field applies a threshold to the taxable amount. Amounts up to and including the threshold are non-taxable. Amounts over the threshold are taxable. The tax rate included in the API response applies to the taxable amount. In this example, the Threshold value is $250, meaning the products you associate with Tax Code PC040100 for this Location would not become taxable until they were sold for more than $250.

Let’s look at a transaction where the LineAmount is $200.00

JurisdictionName LineAmount Tax Base Rate Tax
RHODE ISLAND $200.00 $0.00 0.07 $0.00


No tax should be calculated because the LineAmount is below the $250.00 threshold state in the Tax Content API results.

Now, let’s look at a transaction where the LineAmount is $300.00

JurisdictionName LineAmount Tax Base Rate Tax
RHODE ISLAND $300.00 $50.00 0.07 $3.50


Tax was calculated against $50.00 of the LineAmount because that is the amount that exceeded the $250.00 threshold stated in the Tax Content API results.

Thresholds and TaxAll TaxRuleOption

Assertions

Location Address: 50 5th Ave, New York, NY 10118
Tax Code(s): PC040100

Expected API Result

Assuming nexus is configured for the state of New York, the Tax Content API will produce the following response for the asserted Address and Tax Code. The Tax Content API will return three records that share a single ScenarioId. These results represent the taxing jurisdictions and their associated tax rules and rates that are applicable to the Location and TaxCode specified in the results. These results should be used in conjunction with one another for the specified LocationCode and TaxCode.

[
  {
      "ScenarioId": 1,
      "EffDate": "4/1/2011 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "NY001",
      "TaxCode": "PC040100",
      "ShipToCity": "New York",
      "ShipToCounty": "NEW YORK",
      "ShipToState": "NY",
      "ShipToPostalCode": "10118-0110",
      "ShipToCountry": "US",
      "JurisType": "City",
      "JurisName": "NEW YORK CITY",
      "TaxType": "Sales",
      "Tax_Description": "NY CITY TAX",
      "Tax_Rate": 0.045,
      "Cap": "0",
      "Threshold": "110.000000",
      "TaxRuleOptions": "TaxAll",
      "TaxApplicationLevel": ""
  },
  {
      "ScenarioId": 1,
      "EffDate": "4/1/2012 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "NY001",
      "TaxCode": "PC040100",
      "ShipToCity": "New York",
      "ShipToCounty": "NEW YORK",
      "ShipToState": "NY",
      "ShipToPostalCode": "10118-0110",
      "ShipToCountry": "US",
      "JurisType": "State",
      "JurisName": "NEW YORK",
      "TaxType": "Sales",
      "Tax_Description": "NY STATE TAX",
      "Tax_Rate": 0.04,
      "Cap": "0",
      "Threshold": "110.000000",
      "TaxRuleOptions": "TaxAll",
      "TaxApplicationLevel": ""
  },
  {
      "ScenarioId": 1,
      "EffDate": "4/1/2012 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "NY001",
      "TaxCode": "PC040100",
      "ShipToCity": "New York",
      "ShipToCounty": "NEW YORK",
      "ShipToState": "NY",
      "ShipToPostalCode": "10118-0110",
      "ShipToCountry": "US",
      "JurisType": "Special",
      "JurisName": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
      "TaxType": "Sales",
      "Tax_Description": "NY SPECIAL TAX",
      "Tax_Rate": 0.00375,
      "Cap": "0",
      "Threshold": "110.000000",
      "TaxRuleOptions": "TaxAll",
      "TaxApplicationLevel": ""
  }
]


In this example, the Threshold value is $110 for all three records meaning the products associated with PC040100 for this LocationCode would not become taxable until they were sold for $110.00 or more. Additionally, TaxRuleOptions field includes the “TaxAll” value. With TaxAll, the entire LineAmount becomes taxable once the threshold is met. This is different from the Rhode Island example in the previous section where the amount up to and including the Threshold was bucketed as exempt, while any amount over the Threshold was bucketed as taxable.

Let’s look at a transaction where the LineAmount is $100.00

JurisdictionName LineAmount Tax Base Rate Tax
NEW YORK $100.00 $0.00 0.04 $0.00
NEW YORK CITY $100.00 $0.00 0.045 $0.00
METROPOLITAN COMMUTER TRANSPORTATION DISTRICT $100.00 $0.00 0.00375 $0.00


No tax was calculated because the LineAmount was below the $110.00 threshold state in the Tax Content API results.

Now, let’s look at a transaction where the LineAmount is $125.

JurisdictionName LineAmount Tax Base Rate Tax
NEW YORK $125.00 $125.00 0.04 $5.00
NEW YORK CITY $125.00 $125.00 0.045 $5.63
METROPOLITAN COMMUTER TRANSPORTATION DISTRICT $125.00 $125.00 0.00375 $0.47


Tax was calculated against the entire LineAmount because the LineAmount exceeded the Threshold value and the TaxAll TaxRuleOption was applicable.

Caps

Assertions

Location Address: 201 Criser Hall, Gainsville, FL 32611
Tax Code(s): P0000000

Expected API Result

Assuming nexus is configured for the state of Florida, the Tax Content API will produce the following response for the asserted Address and Tax Code. The Tax Content API will return two records that share a single ScenarioId. These results represent the taxing jurisdictions and their associated tax rules and rates that are applicable to the Location and TaxCode specified in the results. These results should be used in conjunction with one another for the specified LocationCode and TaxCode.

[
  {
      "ScenarioId": 1,
      "EffDate": "1/1/2017 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "FL",
      "TaxCode": "P0000000",
      "ShipToCity": "GAINESVILLE",
      "ShipToCounty": "ALACHUA",
      "ShipToState": "FL",
      "ShipToPostalCode": "32611-4000",
      "ShipToCountry": "US",
      "JurisType": "County",
      "JurisName": "ALACHUA",
      "TaxType": "Sales",
      "Tax_Description": "FL COUNTY TAX",
      "Tax_Rate": 0.005,
      "Cap": "5000.000000",
      "Threshold": "0.000000",
      "TaxRuleOptions": "",
      "TaxApplicationLevel": ""
  },
  {
      "ScenarioId": 1,
      "EffDate": "1/1/2017 12:00:00 AM",
      "EndDate": "12/31/9999 12:00:00 AM",
      "LocationCode": "FL",
      "TaxCode": "P0000000",
      "ShipToCity": "GAINESVILLE",
      "ShipToCounty": "ALACHUA",
      "ShipToState": "FL",
      "ShipToPostalCode": "32611-4000",
      "ShipToCountry": "US",
      "JurisType": "State",
      "JurisName": "FLORIDA",
      "TaxType": "Sales",
      "Tax_Description": "FL STATE TAX",
      "Tax_Rate": 0.06,
      "Cap": "0.000000",
      "Threshold": "0.000000",
      "TaxRuleOptions": "",
      "TaxApplicationLevel": ""
  }
]


In this example, the Cap value is Null for the State record and is $5,000 for the County record. In this scenario, the State rate applies to the entire LineAmount, while the County rate only applies to the first $5,000 of the LineAmount, “capping” the tax amount.

Let’s look at a transaction where the LineAmount is $4,500.

JurisdictionName LineAmount Tax Base Rate Tax
FLORIDA $4,500.00 $4,500.00 0.06 $270.00
ALACHUA $4,500.00 $4,500.00 0.005 $22.50


Tax was calculated on the full LineAmount for the State because there was no Cap stated in the Tax Content API results.

Tax was calculated on the full LimeAmount for the County because the LineAmount was below the $5,000 Cap stated in the Tax Content API results.

Now, let’s look at a transaction where the LineAmount is $7,000.

JurisdictionName LineAmount Tax Base Rate Tax
FLORIDA $7,000.00 $7,000.00 0.06 $420.00
ALACHUA $7,000.00 $5,000.00 0.005 $25.00


Tax was again calculated on the full LineAmount for the State because there was no Cap stated in the Tax Content API results.

Tax was only calculated on the first $5,000 for the county because the LineAmount exceeded the $5,000 Cap stated in the Tax Content API results.

Sales Tax Holidays

Many states offer annual sales tax holidays, providing a reduction or elimination of sales tax on specific categories of products for a short period of time. This section is about interpreting Tax Content API results for Sales Tax Holidays. By the end of this section, you will learn the following:

  • How to interpret Sales Tax Holidays results
  • How to differentiate between Sales Tax Holiday results and normal tax content results

Sales Tax Holiday Results

Assertions

Address: 2501 4th Ave, Canyon, TX 79016-0001
Tax Code(s): PC040100
DocumentDate: 8/10/2017, 8/11/2017

Expected API Result

Assuming nexus is configured for the state of Texas, the Tax Content API will produce the following responses for the asserted Address, Tax Code, and DocumentDates. The Tax Content API will return two records in each response that share a single ScenarioId. These results represent the taxing jurisdictions and their associated tax rules and rates that are applicable to the Location and TaxCode specified in the results. These results should be used in conjunction with one another for the specified LocationCode and TaxCode.

DocumentDate: 8/10/2017

[
    {
        "ScenarioId": 1,
        "EffDate": "8/1/2010 12:00:00 AM",
        "EndDate": "12/31/9999 12:00:00 AM",
        "LocationCode": "TX",
        "TaxCode": "PC040100",
        "ShipToCity": "Canyon",
        "ShipToCounty": "RANDALL",
        "ShipToState": "TX",
        "ShipToPostalCode": "79016-0001",
        "ShipToCountry": "US",
        "JurisType": "City",
        "JurisName": "CANYON",
        "TaxType": "Sales",
        "Tax_Description": "TX CITY TAX",
        "Tax_Rate": 0.02,
        "Cap": "0",
        "Threshold": "0",
        "TaxRuleOptions": "",
        "TaxApplicationLevel": ""
    },
    {
        "ScenarioId": 1,
        "EffDate": "8/1/2010 12:00:00 AM",
        "EndDate": "12/31/9999 12:00:00 AM",
        "LocationCode": "TX",
        "TaxCode": "PC040100",
        "ShipToCity": "Canyon",
        "ShipToCounty": "RANDALL",
        "ShipToState": "TX",
        "ShipToPostalCode": "79016-0001",
        "ShipToCountry": "US",
        "JurisType": "State",
        "JurisName": "TEXAS",
        "TaxType": "Sales",
        "Tax_Description": "TX STATE TAX",
        "Tax_Rate": 0.0625,
        "Cap": "0",
        "Threshold": "0",
        "TaxRuleOptions": "",
        "TaxApplicationLevel": ""
    }
]


DocumentDate: 8/11/2017

[
    {
        "ScenarioId": 1,
        "EffDate": "8/11/2017 12:00:00 AM",
        "EndDate": "8/13/2017 12:00:00 AM",
        "LocationCode": "TX",
        "TaxCode": "PC040100",
        "ShipToCity": "Canyon",
        "ShipToCounty": "RANDALL",
        "ShipToState": "TX",
        "ShipToPostalCode": "79016-0001",
        "ShipToCountry": "US",
        "JurisType": "City",
        "JurisName": "CANYON",
        "TaxType": "Sales",
        "Tax_Description": "TX CITY TAX",
        "Tax_Rate": 0.02,
        "Cap": "0",
        "Threshold": "100.000000",
        "TaxRuleOptions": "TaxAll",
        "TaxApplicationLevel": ""
    },
    {
        "ScenarioId": 1,
        "EffDate": "8/11/2017 12:00:00 AM",
        "EndDate": "8/13/2017 12:00:00 AM",
        "LocationCode": "TX",
        "TaxCode": "PC040100",
        "ShipToCity": "Canyon",
        "ShipToCounty": "RANDALL",
        "ShipToState": "TX",
        "ShipToPostalCode": "79016-0001",
        "ShipToCountry": "US",
        "JurisType": "State",
        "JurisName": "TEXAS",
        "TaxType": "Sales",
        "Tax_Description": "TX STATE TAX",
        "Tax_Rate": 0.0625,
        "Cap": "0",
        "Threshold": "100.000000",
        "TaxRuleOptions": "TaxAll",
        "TaxApplicationLevel": ""
    }
]

In this example, we have two API calls, one with a DocumentDate of 8/10/2017 and another with a DocumentDate of 8/11/2017. You’ll notice, the results of these API calls are different. Specifically, the range of the Effective and End Dates of the second API result fall in between the Effective and End Dates of the first.

If a transaction occurred on or before 8/10/2017, the first response would be applicable because it falls outside of the date range for the SalesTax Holiday Content.

EffDate EndDate JurisName Tax_Rate Cap Threshold TaxRuleOptions
8/1/2010 12/31/9999 TEXAS 0.0625 0 0
8/1/2010 12/31/9999 CANYON 0.002 0 0
8/11/2017 08/13/2017 TEXAS 0.0625 0 100.00 TaxAll
8/11/2017 08/13/2017 CANYON 0.0625 0 100.00 TaxAll


If a transaction occurred between 8/11/2017 and 8/13/2017, the second response would be applicable and the Threshold and TaxRuleOptions should be applied.

EffDate EndDate JurisName Tax_Rate Cap Threshold TaxRuleOptions
8/1/2010 12/31/9999 TEXAS 0.0625 0 0
8/1/2010 12/31/9999 CANYON 0.002 0 0
8/11/2017 08/13/2017 TEXAS 0.0625 0 100.00 TaxAll
8/11/2017 08/13/2017 CANYON 0.0625 0 100.00 TaxAll


If a transaction occurred after 8/14/2017, the first response would again be applicable because it falls outside of the date range for the SalesTax Holiday Content.

EffDate EndDate JurisName Tax_Rate Cap Threshold TaxRuleOptions
8/1/2010 12/31/9999 TEXAS 0.0625 0 0
8/1/2010 12/31/9999 CANYON 0.002 0 0
8/11/2017 08/13/2017 TEXAS 0.0625 0 100.00 TaxAll
8/11/2017 08/13/2017 CANYON 0.0625 0 100.00 TaxAll


The Tax Content API only supports a single DocumentDate per API call, but users are able to call the API with a post-dated DocumentDate to retrieve content that will be effective in the future.