11.3 - Tax Content API

• Previous
• Next

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:

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

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

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

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.

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.

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.

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. An example of a sales tax holiday is an annual “Back-To-School” sales tax free weekend.

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 best use the tax content API to anticipate sales tax holidays
• How to interpret Sales Tax Holidays results
• How to differentiate between Sales Tax Holiday results and normal tax content results

Anticipating Sales Tax Holidays

Because tax holidays are controlled be legislation, some legislation may be finalized well in advance of the actual holiday whereas other legislation will be finalized only shortly before the actual holiday. Avalara will update its tax content to reflect sales tax holidays only after legislation has been passed and signed into law.

When using the offline tax content API, Avalara encourages you to re-download data regularly to ensure that recently passed and signed legislation will be included in your offline tax content. Please consider the possibility of tax holidays when deciding on your download schedule. If you pick a download frequency of once per month, for example, a sales tax holiday law that was passed and signed after your most recent download will not be reflected in your tax content file.

Avalara encourages customers using offline tax content to download their tax content data once per day in the morning. This can be implemented as a normal morning “start-up” process for your cash register or point-of-sale application.

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.

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.

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.

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.

Keep in mind that as you download data for future dates, sales tax laws can change based on decisions made in the legislative process. If you download data for a time period in the future and tax laws change, you would need to re-download tax content for that date in order to process the latest rates.

For best practices, Avalara encourages you to re-download your tax content data once per day during your startup process.

• Previous
• Next