Avalara Developer Network Developer communications

Chapter 2 - Calculate Taxes

Your First CalcTaxes Request

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

Headers

Add these 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",
        "city": "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?

  1. Your company details (cmpn)
  2. Invoice (inv) details
    • DocumentCode (doc) is included so we can commit this transaction later
    • The Commit flag (cmmt) is set to false. If you want to commit immediately, set the Commit flag to true in the transaction.
    • BillTo (bill) is a Location object and is specified in different ways. We pass a combination of Country (ctry), City(city), State (st), and Postal Code (zip), but we can also pass a single PCode (pcd), FIPS (fips), or NPANXX (npa) value.
  3. The value you assign to the date key is important because it 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.
  4. The LineItem (itms) is contained within the Invoice. This is where you enter information such as Charge (chg), Transaction/Service Pair (tran and serv), and number of Lines (line).

Response

The response contains a list of detailed tax amounts (txs):

{
    "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

For more information, see CalcTaxes Response.