Avalara Developer Network Developer communications

Chapter 2 - Calculate Taxes

Your First CalcTaxes Request

Let’s dive right in. We’re going to send a simple CalcTaxes call using Postman and inspect the results.

Headers

Add the following mandatory headers to your request:

  • api_key
  • client_id
  • Content-Type: application/json

Postman example

Body

For the body of the POST request, copy and paste the following example:

{
  "cmpn": {
    "bscl": 1,
    "svcl": 1,
    "fclt": true,
    "frch": true,
    "reg": true
  },
  "inv": [
    {
      "doc": "DocumentXYZ123",
      "bill": {
        "ctry": "USA",
        "st": "NC",
        "cty": "Durham",
        "zip": 27701
      },
      "cust": 1,
      "date": "2018-09-24T11:00:00",
      "itms": [
        {
          "chg": 100,
          "line": 10,
          "sale": 1,
          "tran": 19,
          "serv": 6
        }
      ]
      "cmmt": false
    }
  ]
}

What are we sending?

In the example above, our request body begins with information that describes your company (cmpn).

Next comes the Invoice (inv). This object contains details of the transaction(s). We’ve included a document code so we can commit this transaction later. Our BillTo Location (bill) is a Location object and can be specified in several ways. In this example, we passed in a combination of Country, City, State and Zip Code, but we can also pass a single PCode, FIPS, or NPANXX value. Because we didn’t specify a Street Address (addr), the tax engine will make a best effort guess a location when determining tax jurisdiction.

The value you assign to the date key is important: this affects which rules are used by our tax engine to calculate taxes. Tax rules change frequently and our Content Team continuously updates our tax engine to reflect these changes.

Inside the Invoice is a LineItem(itms). This is where information like the Charge, Transaction/Service Pair, number of Lines, etc. is stored.

At the bottom of the JSON object we’ve set the Commit flag (cmmt) to false. This is the default behavior so this line is optional, but you can set the flag to true if you want to commit the transaction without using the Commit API later.

Response

The response contains a list of tax amounts:

{
    "inv": [
        {
            "doc": "DocumentXYZ123",
            "itms": [
                {
                    "txs": [
                        {
                            "bill": true,
                            "cmpl": true,
                            "tm": 111.813098,
                            "calc": 1,
                            "cat": "SALES AND USE TAXES",
                            "cid": 1,
                            "name": "North Carolina Telecommunications Sales Tax",
                            "exm": 0,
                            "lns": 0,
                            "min": 0,
                            "pcd": 2716900,
                            "rate": 0.07,
                            "sur": false,
                            "tax": 7.8269168600000008,
                            "lvl": 1,
                            "tid": 231
                        },
                        {
                            "bill": true,
                            "cmpl": true,
                            "tm": 64.9,
                            "calc": 1,
                            "cat": "CONNECTIVITY CHARGES",
                            "cid": 5,
                            "name": "FUSF (VoIP)",
                            "exm": 35.099999999999994,
                            "lns": 10,
                            "min": 0,
                            "pcd": 0,
                            "rate": 0.179,
                            "sur": false,
                            "tax": 11.6171,
                            "lvl": 0,
                            "tid": 162
                        },
                        {
                            "bill": true,
                            "cmpl": true,
                            "tm": 64.9,
                            "calc": 1,
                            "cat": "REGULATORY CHARGES",
                            "cid": 6,
                            "name": "FCC Regulatory Fee (VoIP)",
                            "exm": 35.099999999999994,
                            "lns": 10,
                            "min": 0,
                            "pcd": 0,
                            "rate": 0.00302,
                            "sur": false,
                            "tax": 0.19599800000000003,
                            "lvl": 0,
                            "tid": 226
                        }
                    ]
                }
            ]
        }
    ]
}

Each tax amount returned contains additional information including:

  • bill: Is the tax billable? Or, can this tax be passed on to the end-customer?
  • cmpl: Will this tax be included in compliance reporting?
  • tm: Taxable Measure
  • cat: Tax Category
  • rate: Tax Rate
  • lvl: Tax Level (Federal, State, County, Local)
  • tax: Tax Amount

More information about the CalcTaxesResponse can be found here.