Introduction
"I just need to get the tax rate for a ZIP code!"
That’s what I often hear from people when they’re first approaching a sales tax integration project. I totally get that preconception—I used to think that way, too!—but that’s a mindset from a long time ago, when matching rates with ZIP codes was all computers could do.
A lot has changed since then, both with technical capabilities and with tax law, and we built the AvaTax API to keep up with both the complexity and the possibilities.
Different products are taxed very differently now—whether it’s soft drinks or software or ski boots—and it’s not always clear when you need to collect tax based on the destination or the origin. Just to give you an idea of the complexity of tax compliance, our API reconciles between two and three thousand different product categories, all taxed differently across more than 10,000 separate (but often overlapping) tax jurisdictions, from cities to counties to states to countries.
Basically, the AvaTax API takes the crazy hairball that is tax compliance and makes it painless for developers, so they can easily integrate powerful and accurate tax calculations into any accounting system.
Scenario #1: Sweater for sale
So how does the AvaTax API work, and what makes it better than a standard, off-the-shelf tax solution? It’s probably easiest to walk through a couple of examples.
In the sample scenario below, we can see how the API can accurately calculate tax for shipping a $100 cloth sweater from California to New York. Did you know New York has special tax rules for clothing products? AvaTax does—and the taxCode value specific to the sweater leverages the constant work of Avalara’s content team, which monitors governments around the world and tracks whenever a tax rule or rate changes for a particular type of product or service.
Likewise, the postalCode value makes sure that tax gets calculated correctly according to rules for different tax jurisdictions, whether you’re shipping from California to New York or the other way around.
POST /api/v2/transactions/create
{
"lines": [{
"amount": 100,
"taxCode": "PC040100"
}],
"type": "SalesInvoice",
"companyCode": "DEFAULT",
"date": "2017-10-02",
"customerCode": "ABC",
"addresses": {
"shipFrom": { "postalCode": "90210" },
"shipTo": { "postalCode": "10010" }
}
}
Another great thing about the way these values are used is that the AvaTax API grows as a company’s tax situation becomes more complex. The Avalara content team is constantly researching changes in tax laws and making sure that they’re reflected in the API—so taxes get calculated accurately no matter how complex things get.
Scenario #2: Multiple vendors
Say you’re attempting to build the next generation of Etsy or eBay, and you want to open up a marketplace with multiple sellers. Tax laws require each transaction to be filed separately—but if your marketplace wants to make things easy for customers, AvaTax can help.
If someone logs onto your store and buys three different things from three different vendors, the AvaTax API can break up a multi-company transaction and turn it into individual transactions, so that each of your sellers can file their taxes separately, as you can see below.
POST /api/v2/transactions/multidocument
{
"lines": [{
"amount": 100,
"taxCode": "PC040100",
"companyCode": "SELLER1"
},{
"amount": 100,
"taxCode": "PC040100",
"companyCode": "SELLER2"
},{
"amount": 100,
"taxCode": "PC040100",
"companyCode": "SELLER3"
}],
"type": "SalesInvoice",
"date": "2017-10-02",
"customerCode": "ABC",
"addresses": {
"shipFrom": { "postalCode": "90210" },
"shipTo": { "postalCode": "10010" }
}
}
Easy integration
Like most of my team, I was a developer and consultant long before I came to Avalara, so we all know what it’s like to build integrations, both for smaller firms and for enterprises. That means we’re always wracking our brains to make tax calculations as easy and self-serve as possible and to give developers as much control as possible. That’s the philosophy behind our documentation and sample code, too.
From the beginning, we’ve tried to make the AvaTax API really easy to use, and one of my favorite integration stories happened last year: We were working with a big partner, an enterprise-level e-commerce company, and they wanted to implement the API across their entire marketplace platform. The execs all agreed on a handshake deal at the end of the week, and then they assumed that integration would take two or three months. But the partner came back the following Monday and said, "I guess we don’t need any more help after all. We gave it to some junior guys and they got it done over the weekend." Yep, we’re proud of our documentation.
Take the next step: Try it yourself
Back in the old, "I just need the tax rate for a ZIP code!" days of tax compliance, there was often a big discrepancy between the tax that was collected and the tax that was owed at the end of a given month—and not surprisingly, that meant companies were more vulnerable to audits and could get dinged with penalties and interest.
With the speed and precision that’s possible now, our API makes it possible for companies to reconcile their tax collection and remit values down to within a dollar—which is kind of astounding given all the rounding and complexity involved. (And that accuracy means companies usually don’t get audited, or if they do, that they don’t see a negative result.)
If you’re building any kind of tax integration, I invite you to check out our Developer Guide, look at our SDKs (including for C#, JRE, PHP, Ruby, and JavaScript), and sign up for a free 60-day production account to try the AvaTax API out yourself. You’ll find that the API can help with other complex tasks, too, like automating exemption-certificate management processing.
Still got questions? Come talk to me and my team! We’ve started doing weekly, open-door Office Hours, just for developers and engineers. Whether you’re new to the Avalara platform or you’re interested in adding features or increasing capabilities, we know how to get stuff done and we’re ready to help you out.
