Avalara Developer Network Developer avaTax

Four simple steps to getting started inĀ calculating sales tax with our RESTĀ API

If you already have an Avalara AvaTax account and want to dive into the details, a good place to start is our Introduction to the Avalara AvaTax API.

1 Try the API

Want to know how the API looks? Make some requests with the tool below. See how different inputs produce different tax calcluation results, and see what kind of tax information you can expect to get back.

2 Create a Sandbox Account

This sandbox account is for evaluation only and is initially active for 90 days, but you can request an extension if needed. You will need to add company profile and tax profile information to calculate sales tax. It is based on an AvaTax Basic subscription and includes access to Nexus Jurisdictions in the U.S. and Canada only. To access full AvaTax Pro System Tax Code functionality or Global Nexus Jurisdictions, please contact sales to inquire about a paid development account.

3 Log in to the Admin Console

Visit our AvaTax Development Admin Console and you will be prompted to change your password. In addition to changing your password, you will need to add a company and some nexus jurisdiction selections to get any tax results.
Note: In order to match the sample code we provide, use CompanyCode APITrialCompany when creating your company. If you use some other CompanyCode value remember to change the value in your samples.

4 Make a Tax Call

Now that you have an account with company settings, you are ready to make an API request! We have automatically filled in the required POST parameters to calculate the sales tax on a $10 sale amount using the Avalara corporate address at 100 Ravine Lane, Bainbridge Island, WA.
POST REQUEST
We will make a POST request to URL:
https://development.avalara.net/1.0/tax/get
Use your favorite Base64 encoding program or perhaps one of the REST client apps for Google Chrome to create a Basic Authorization Header from your username and password. It will look something like this:
Authorization: Basic c29tZS51c2VyQGNvbXBhbnkuY29tOlA0JCR3MHJk
The POST body will be:
{
  "DocDate": "2013-01-16",
  "CustomerCode": "CUST1",
  "DocCode": "DOC0001",
  "DocType": "SalesInvoice",
  "Addresses":[{
    "AddressCode": "1",
    "Line1": "100 Ravine Lane NE",
    "City": "Bainbridge Island",
    "Region": "WA",
    "PostalCode": "98110"
  }],
  "Lines":[{
    "LineNo": "1",
    "DestinationCode": "1",
    "OriginCode": "1",
    "Qty": 1,
    "Amount": 10
  }]
}
DocDate is the date used to calculate the tax, and to identify the date on which the invoice is recorded. This should be your invoice date. CustomerCode uniquely identifies the end customer making the purchase. DocCode is a unique identifier of the transaction. This is often invoice number. DocType tells Avalara what kind of transaction this is. In this case, it is a document that represents a sale, and should be saved in our database. Address in this case is used as both the origin and destination. In general, these may not be the same. Lines is an array of all line items on the invoice (including any freight and miscellaneous charges). Each invoice line should be a line on the tax request, and should specify a line number (unique within the document), quantity, and extended amount.
IMPORTANT:
  • The dollar amount must be nonzero to calculate nonzero tax (tax on $0 will always be $0).
  • You will need your account credentials (Username and Password) to make a successful API call.
POST RESPONSE
{
  "DocCode": "DOC0001",
  "DocDate": "2013-01-16",
  "Timestamp": "2013-02-12T23:45:02.687",
  "TotalAmount": "10",
  "TotalDiscount": "0",
  "TotalExemption": "0",
  "TotalTaxable": "10",
  "TotalTax": "0 .86",
  "TotalTaxCalculated": "0.86",
  "TaxDate": "2013-01-16",
  "TaxLines": [{
    "LineNo": "1",
    "TaxCode": "P0000000",
    "Taxability": "true",
    "BoundaryLevel": "Address",
    "Exemption": "0",
    "Discount": "0",
    "Taxable": "10",
    "Rate": "0.086000",
    "Tax": "0.86",
    "TaxCalculated": "0.86",
    "TaxDetails": [{
     "Country": "US",
     "Region": "WA",
     "JurisType": "State",
     "Taxable": "10",
     "Rate": "0.065000",
     "Tax": "0.65",
     "JurisName": "WASHINGTON",
     "TaxName": "WA STATE TAX"
    },
    {
     "Country": "US",
     "Region": "WA",
     "JurisType": "City",
     "Taxable": "10",
     "Rate": "0.021000",
     "Tax": "0.21",
     "JurisName": "BAINBRIDGE ISLAND",
     "TaxName": "WA CITY TAX"
    }]
  }],
  "TaxAddresses": [{
    "Address": "100 RAVINE LN NE",
    "AddressCode": "1",
    "City": "BAINBRIDGE ISLAND",
    "Country": "US",
    "PostalCode": "98110-2687",
    "Region": "WA",
    "TaxRegionId": "2109716",
    "JurisCode": "5303503736"
  }],
  "ResultCode": "Success"
}
Document-level tax calculation results are available at the root level of the response, notably TotalTax. This is the total amount of tax calculated on the invoice. Each Line item in the request is represented in the response by a TaxLine, which shows line-level tax calculation results. The jurisdictional breakout of the tax calculation for each line is displayed as an array of TaxDetails.
Verify Your Results in the Admin Console
The tax request you made in Step 3 will be viewable in the Admin Console. Log in and navigate to the Transactions tab to verify that you have produced a successful outcome.
Example of successful outcome Example of successful outcome
Moving forward, it's a good idea to periodically review the Admin Console to verify that you're heading in the right direction.

What's Next?

If you didn't already check out the Introduction to the Avalara AvaTax API, that's where you should go next. As you're designing your integration, you'll want to consider what kind of use cases you need to accommodate. We also recommend that you take a look at the API Reference, review our integration checklist, and check out the Developer Community.