Avalara Developer Network Developer blog

REST v2.3.1 Patch Notes

REST v2.3.1 Patch Notes

For those of you who participated in the AvaTax REST v2 Preview program, I’d like to take this opportunity to thank you for your time and effort helping us debug a huge software release. We’ve now implemented a clean, modern, consistent REST API that covers tax functionality from top to bottom - and we’ve established a great platform for continuing improvements.

Now that the program is winding down, please take note of a few differences between the final release of REST v2 and the preview program you tested in August/September:

New URL for REST v2

The existing URL, https://rest-sbx-preview.avalara.net, will be retired and no longer available after October 25th, 2016.

If you have any applications or services using this URL, please update them to point to the new URLs:

Changes to /api/v2/transactions/create

The /api/v2/transactions/create endpoint now only allows creation of one transaction at a time.

If any of your existing programs were creating multiple transactions with a single API call, you will need to:

  • Modify them to use one API call per each transaction, or
  • Modify them to use the /api/v2/companies/123/batches/create endpoint instead.

Posting and Committing Transactions

To avoid confusion between the action “POST” and the HTTP verb “POST”, we have renamed and simplified the /api/v2/transactions/123/post API call to “settle”. Some users were also confused about the difference between a call to /api/v2/transactions/123/post vs a call to /api/v2/transactions/123/commit. To reduce this confusion, we have split these API calls into individual functions:

POST /api/v2/companies/ABC/transactions/DEF/verify

Ensures that a transaction’s amounts match an expected value, and returns an error if they do not match.

POST /api/v2/companies/ABC/transactions/DEF/changecode

Changes the transaction code of a specified transaction.

POST /api/v2/companies/ABC/transactions/DEF/commit

Commits a transaction so that it can be reported in a tax return.

Each of these three APIs is separate and does not depend on the others. Once you have created a transaction, you can call any of these three APIs to execute any one of these three functions separately. If you’d still like to call all three of these API calls at once, you can use “settle”:

POST /api/v2/companies/ABC/transactions/DEF/settle

This endpoint allows you to execute all three actions, verify, changecode, and commit, in a single API call.

Single Object Creation

If you call an API that allows multiple object creation, but you forget to send an array, our API will now accept a single object and continue to work rather than reporting an error.

Improved API Documentation

When browsing the online swagger documentation for REST v2, you will notice that objects have rewritten help text and example objects visible within the online documentation.

Error Messaging Improvements

Error Message objects have been rewritten to match Microsoft’s updated Error Message standards, and all error messages contain a URL that points to a web page explaining the error in detail. Here’s an example of the new error objects:

{
  "error": {
    "code": "ModelStateInvalid",
    "message": "One or more parameters in your request were incorrect.",
    "target": "HttpRequest",
    "details": [
      {
        "code": "ModelStateInvalid",
        "number": 70,
        "message": "One or more parameters in your request were incorrect.",
        "description": "The value '-0-' is not a valid 'id'.",
        "faultCode": "Client",
        "helpLink": "/avatax/errors/ModelStateInvalid",
        "severity": "Error"
      }
    ]
  }
}

You can preview a list of error messages recognized by AvaTax REST v2 on the /avatax/errors/ page.

Client Identification

In each AvaTax API request, you can provide a request header called X-Avalara-Client. This value identifies your application and helps Avalara track down problems and identify when customers are using an outdated version of the software.

The client identification tag looks like this:

X-Avalara-Client: (application name); (application version); (library name); (library version); (machine name)

Other Improvements

We made hundreds of individual improvements to the API based on your feedback and based on internal testing. Many of these changes helped to clarify error messages that were confusing, or identify unsafe API calls - calls that would result in invalid tax configuration settings, for example.

We welcome your feedback - please continue to share your experience of the REST v2 API and we will be happy to continue to work with you!

–Ted Spence, Director, AvaTax Core Engine

Subscribe via RSS!

Back to posts