1.1 - Connecting to the API

To get started, you’ll need an AvaTax account. Avalara provides free trial accounts you can use to begin developing against AvaTax. This trial account will allow you to use advanced AvaTax functionality for locations in the U.S. and Canada.

You can begin by signing up for a free AvaTax account online, or you can contact sales to purchase an account. Once your free trial is up, you can continue using our Free TaxRates API or contact sales to upgrade to a full account.

The AvaTax Website and Tax Profiles

When your account is provisioned, you will receive an email inviting you to log onto the AvaTax website. We create a basic tax profile for you when you signup for the free trial using the information you provided. If you would like to change these settings, login to the AvaTax UI and you’ll be able to update your tax profile. A tax profile tells AvaTax where your company does business and where you have nexus.

It’s important to understand the concept of nexus. You can think of it as “a list of places where I must collect tax;” - this is an important concept for all AvaTax developers. If you do not declare any nexus, your account will not calculate any tax! We’ll cover this topic in more detail in Chapter 8.1 - Reasons Tax Can Be Zero.

This nexus concept may seem strange at first, but it helps you separate your tax software from your tax profile. When integrating tax into your program, you want to write the code once and test it once. Your code doesn’t need to know where you have nexus; AvaTax takes care of that for you. As a programmer, your job is to make the software reliable and accurate; your accounting team will then manage your company’s nexus settings on an ongoing basis. By using a concept of nexus separate from your software, you won’t have to go back and rewrite your program later when your company’s nexus changes.

  • If you are building an AvaTax integration for your company, you’ll probably need to work with your tax team to ensure that your account and tax profile are set up correctly before you start developing software. If you forget to set up a tax profile, you may find that your tax calculations keep coming back with a rate of zero, because the tax profile doesn’t require you to collect tax!

  • If you’re building an integration to an accounting system or storefront system - a connector - the companies that purchase your connector will need to set up their own tax profile. This means that you can develop your software without having to know anything about your customers’ tax profile. As long as you follow the AvaTax certification guidelines in this developer guide, a customer that purchases your connector will be able to set up their own tax profiles and get accurate tax results.

What is Sandbox?

Next, let’s explain what we mean by Sandbox. Avalara provides two different environments for AvaTax: Sandbox and Production. Each environment is completely separate, and each has its own credentials. If you have a Sandbox account, you cannot use that account to log onto Production; and vice versa.

When you receive credentials for AvaTax, it’s important to write down the account’s environment name. We keep Sandbox and Production credentials separate to help you test your software in Sandbox without the risk of accidentally affecting production data.

You may want to share your sandbox credentials with deveopers, and reserve production credentials for accountants. Keeping accounts separate helps avoid the risk of reporting test data to a tax authority.

Let’s spend a few minutes explaining how Sandbox and Production relate to each other.

Sandbox Production
AvaTax Website URL https://sandbox.admin.avalara.com https://admin.avalara.com
Tax Content Always kept up to date Always kept up to date
Monitoring 24/7 Monitoring 24/7 Monitoring
Data All Sandbox data is fully separate from Production data. All Production data is fully separate from Sandbox data.
Credentials Production credentials will not work on Sandbox, so you can't accidentally save a real transactions into the sandbox environment with a production account. Sandbox credentials will not work on Production, so you can't accidentally create a test transaction in production with a sandbox account.
Tax Filing Sandbox data is never reported to a tax authority; so you can test your transactions without worrying about accidentally reporting transactions. Transactions that are marked Committed in production can be reported on a tax filing using the Avalara Managed Returns Service.
Updates Generally updates a few days earlier than Production, so that customers can experiment with new releases before they go live. Updated a few days to a week after Sandbox, so that customers can preview the new release on Sandbox before it is live.

For more information on Sandbox and the AvaTax release schedule, please read The AvaTax Release Schedule.

AvaTax Software Development Kits

You don’t have to write all your code from scratch! Our team has built AvaTax Software Development Kits for a variety of popular programming languages to help you get started more quickly. The AvaTax SDK includes shortcuts to help set up authentication, call API methods, and parse results - so you can focus on the valuable business logic.

The AvaTax SDK is fully open source, and you can download source code for a myriad of languages and frameworks. You will find officially supported libraries and those that are contributed by our community on the AvaTax SDK page. We welcome your feedback - if you wish to report a bug or submit a question, please contact us using our support page or submit a pull request directly to the GitHub repository for each SDK.

If you choose, you can always write your own code to contact the AvaTax API directly. We publish all of our API reference documentation online, and every API has an interactive ‘Try-It-Now’ feature so you can get familiar with our service. Our internal developers use the exact same documentation that we publish to our partners and customers, so you know you’ll always see the latest information online.

Now that we’ve got the basics out of the way, let’s set up authentication and start using the API!