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:

  • Authorization using basic HTTP authentication
  • client_id
  • Content-Type: application/json

Postman Authorization Example

Postman Headers Example

Body

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

{
  "cmpn": {
    "bscl": 1,
    "svcl": 1,
    "fclt": true,
    "frch": true,
    "reg": true
  },
  "inv": [
    {
      "doc": "DocumentCode12345",
      "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
    • Document Code (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 invoice.
    • 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 CalcTaxes response contains a list of detailed tax amounts (txs):

{
    "inv": [
        {
            "doc": "DocumentCode12345",
            "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 detailed tax record 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.

PreviousNext