After your application detects a timeout, it must decide whether to retry the transaction or fallback to a default tax rate. We can’t recommend which specific approach to use for your program, but we can encourage you to consider a few key risks when retrying a transaction:

Some programs attempt to reuse HTTP connections. If you experience a connection disruption, we encourage you to create a new connection for the next attempt.

If you experienced a timeout, you don't know whether AvaTax received your original API call. AvaTax might have received and process the API call successfully, but your code didn't receive the response. If you attempted to create a permanent document such as a SalesInvoice, retry your transaction using CreateOrAdjustTransaction. This API call will work correctly in either case: if the original API call failed, this call will create the document; if the original API call succeeded, this API will adjust the transaction.

If you decide instead to fallback to a default rate, you have a different set of concerns:

For transactions shipped around the country, a customer might not be obligated to collect tax in each jurisdiction they didn't set up their company to collect tax in that jurisdiction. If you collect tax in a jurisdiction, you must pay it.

Tax rates vary by product type, sourcing rules, and other considerations. If you use a default tax rate that happens to be higher than the actual final tax rate, you must pay the "OverCollected" amount.

AvaTax provides two approaches to fallback tax if the application times out: a DownTaxRatesByPostalCode API and a BuildTaxContentFile API. Whichever approach you select, keep in mind the cardinal rule of tax auditors: whatever amount of tax you collect, you must pay. If you accidentally over collect tax, you must still pay the amount you collected. If you collect tax in a jurisdiction where you aren't registered as a business, decide whether to register your business and begin filing taxes or to refund the tax collected to the customer. For specific advice on tax over collection policies, contact Avalara’s Professional Services team.

DownloadTaxRatesByPostalCode API

Avalara provides a DownloadTaxRatesByPostalCode API, which includes a postal code rates table that you can use to determine the sales tax rate for tangible personal property in a jurisdiction. This approach produces a simple rate value; however it overlooks much of the complexity of tax law. As such, the calculated tax might not accurately reflect the amount of tax required to collect in that jurisdiction.

If you use this approach, keep in mind that sales tax rate changes take effect on the first day of the month. To stay current, we recommend that you set up a reoccurring task to grab the rates regularly. Avalara generally updates rates once a month. Use using a date of your choice in the request. For example:

https://rest.avatax.com/api/v2/taxratesbyzipcode/download/7-1-24

TaxContent API

For another approach, AvaTax provides a TaxContent API for you to determine sensible default tax rates for your locations. This API delivers more precise tax rates for various locations around the United States and is especially useful for programmers developing a retail point of sale (POS) based solution. The API produces a file that contains tax rates and rules for items and locations that can be used to correctly calculate tax in the event a POS device isn’t able to reach AvaTax.

Here’s how the TaxContent API works:

Use the CreateLocation API to create one location record for each physical retail presence you have.

Determine all the TaxCodes appropriate to products sold by your business.

On startup, your program calls the BuildTaxContentFile API to download default tax rates for the matrix of locations and tax codes for today.

This data file will help ensure more accuracy in your tax calculation. It's not a perfect substitute for calling CreateTransaction directly, but it’s more precise than using a default rate for a postal code.

Retry or fallback