AvaTax API 17.12 Patch Notes
By Ted Spence | Nov 27, 2017

This article is about the December 2017 monthly update to the AvaTax API.

Environment URL Release Date
Sandbox https://sandbox-rest.avatax.com 2017-12-11
Production https://rest.avatax.com 2017-12-14

Performance Tuning

During the months since the 17.9 Patch Notes, our team has been hard at work tuning the performance of AvaTax for the once-a-year sales events that happen in November. Here's a summary of the improvements that have been made since the September release:

  • Reduced the impact of calling the GetTransactionByCode API and GetTransactionByTypeAndCode API. This change improved performance for customers whose products used a mix of calls to these APIs alongside creating new transactions.
  • Eliminated caching delays caused by updating user credentials or license keys rapidly before they had time to propagate through the AvaTax storage cluster.
  • Enforced a limitation on the ListTransactionsByCompany API to avoid extremely long timeouts for customers with a large number of transactions. By default, this API now limits you to fetching data within the current 30-day window.
  • Better query optimization when fetching data from our data store, and better use of our three-tiered data caching strategy throughout the REST API.
  • Improved performance for the free TaxRatesByPostalCode API.

These changes were released gradually during the October and November timeframe as our team prepared for Black Friday and Cyber Monday sales events.

MultiDocument API Suite

Are you building a marketplace website that provides the ability for a wide variety of vendors to list their wares? Does your company make purchases for multiple business entities with a single transaction? If so, you may be a candidate for Avalara's newest API: the MultiDocument API Suite.

This collection of APIs makes it convenient to record a transaction for a variety of vendors in one place, and to automatically break up the transaction so that it can be reported on multiple separate tax returns, one per business entity. We'll update our documentation for this feature and share with you a variety of blog posts explaining how this API suite can help you create, track, adjust, and reconcile transactions in a multi-vendor marketplace.

Support for Country and Region Naming

As of the December release of AvaTax, all of our APIs now allow you to specify full length country names, abbreviations, and even some common misspellings of various countries. We have subscribed to the International Standards Organization's ISO3166 database, which provides us with official names and abbreviations of countries and region codes throughout the world and in many popular languages.

All of this data and localized names are now available to you through the ListCountries API and ListRegions API. Try out the API and see what you can find!

Now that you are able to use fully spelled out names of countries and regions in all AvaTax APIs, here are a few examples:

  • You can now use UNITED STATES as well as US when referring to the United States.
  • You can now use CALIFORNIA as well as CA when referring to the west coast state.
  • You can now use ZURICH or ZÜRICH as well as ZH when referring to the region within Switzerland. Character accents are optional, but supported.
  • You can now use GERMANY or DEUTSCHLAND or ALLEMAGNE as well as DE to refer to the Republic of Germany. The same country name is available in certain formally recognized linguistic variants.

Changes to CreateTransaction

A variety of improvements and bugfixes have been made to the CreateTransaction API.

  • If you omit the field date when calling the CreateTransaction API, you will now get a proper error message indicating that the field cannot be null or empty.
  • For consistency, the field customerUsageType is being replaced with entityUseCode. We have chosen to standardize on the naming of this field all throughout our API; so please expect to see the same field have the same name in all instances.
  • Fixed a bug where transactions in Canada would occasionally see incorrect jurisdiction type ID values when using the transaction type SalesOrder.
  • Fixed an unhandled exception when sending referenceCode fields longer than 1,024 characters.
  • Fixed an unhandled exception when transmitting unusual values in the type field for tax overrides.
  • Marked the lines element as required, since a transaction cannot be created if there are no invoice lines on it.
  • Improved documentation for the isSellerImporterOfRecord and taxIncluded fields.
  • Added a new field, totalDiscount, to the transaction model. This field contains the sum of all discounts for each individual line in the overall transaction.

Other Improvements

  • The LockTransaction API now gives an error message if you call it without returns enabled.
  • The ResolveAddress API will return an error message if you attempt to validate addresses in a country that is not supported by Avalara's address matching logic.
  • Improved documentation and error messages for the ChangeTransactionCode API.
  • Removed the trace file from the filing confirmations download API. Payment traces can now be downloaded through a separate API call.
  • Improved the use of example objects in the API documentation and added tests to ensure that all models used in the API have a valid example object.
  • Improved the error messages provided when a user attempts to change their security role without sufficient permissions.
  • Improved data store operations on the tables related to the reporting API.
  • Updated documentation for a variety of APIs
  • Improved model validation for complex nested models. You should now see better validation errors for all sorts of data problems in the API.
  • Improved caching for code that checks your returns filing configuration.
  • Improved documentation for nexusTypeId in the Nexus API suite.
  • The CreateUser API has been moved to the Users API suite, and its documentation has been updated to indicate that it is available to use to generate users.
  • New API available for determining the status of a tax filing quickly by its filing calendar ID.
  • Updated the AddLines API to work with $include options.
  • Marked the verifyTransactionDate parameter as optional in the VerifyTransaction API.
  • Improved documentation for the X-Avalara-Client parameter for all APIs.
  • Corrected an issue that incorrectly marked registrationId field as required for filing requests.


  • Fixed a bug in the BuildTaxContentFile API that caused certain sales tax holidays to appear incorrectly. Another problem caused jurisdictions with commas in their names to parse incorrectly.
  • Fixed an unhandled exception when you provided a date value earlier than the year 1900.
  • Fixed an unhandled exception when saving negative adjustments to tax filings.
  • Fixed a variety of unhandled exceptions with complex ?$filter= query string parameters. One error was only triggered if you specified a field name but no operation; another error occurred if you specified multiple clauses within an API call but forgot a conjunction between clauses. Other errors could occur if you specified certain criteria that were not supported on specific data models.
  • Fixed an unhandled exception in the RefundTransaction API that occurred when certain fields were left null or omitted.
  • Fixed an unhandled exception that occurred if you called the CreateLocations APIa when one of the settings elements had a name with an inappropriate length.
  • Fixed an unhandled exception that occurred if you attempted to fetch return filings using undefined or empty values, or if you attempted to fetch a specific tax filing with an invalid ID number.
  • Fixed an unhandled exception in the configuration settings for communications tax
  • Fixed an unhandled exception when fetching reports that do not exist.
  • Fixed a problem with the filing confirmation API that would prevent downloading of some Streamlined Sales Tax returns.
  • Fixed an unhandled exception that could occur when adding lines to a transaction that was created with older versions of the AvaTax software.
  • Fixed an unhandled exception that could occur if you transmit a null post body to the CreateTaxCodes API, or if you were to send in a null or invalid company reference.
  • Fixed an unhandled exception in the TaxContent API suite that occurred if you attempted to build tax content files for an invalid location code.
  • Fixed an unhandled exception on the RequestNewAccount API that occurred if you omitted the postal code or accidentally sent data too long for the field.
  • Fixed an issue that caused incorrect tax authorities to be listed in some nexus queries.

-- Ted Spence, Director, AvaTax Core Engine