Chapter 4.3.3 - Jurisdiction Determination

Jurisdictions are set on the invoice and the line item for a CalcTaxes request.

Key Location Name Description
bill BillTo Location used to specify where the transaction is to be billed

Required on the invoice, but can also be set on the line item (overrides BillTo set on the invoice)
from From (Origination) Specifies the point of origin for the line item. Defaults to the BillTo location if not set
to From (Destination) Specifies the point of termination for the line item. Defaults to the BillTo location if not set

See Location for more information.

A jurisdiction is set with one of these jurisdiction types:

  • PCode (pcd): Persisted numeric identifer for a taxing jurisdiction
  • Address: Specify a Country (ctry), State (st), County (cnty), City (city), and/or Postal Code (zip). Set the Street Address (addr) if you want to geocode the address (geo = true)
    • The more complete the address information provided, the more accurate the results are
    • Country ISO is sufficient for taxation purposes for most foreign nations other than USA, Canada, and Brazil
    • Country (ctry), State (st), and Postal Code (zip) are required for USA and Canada (at a minimum)
  • FIPS (fips): Standardized set of numeric or alphabetic codes issued by the National Institute of Standards and Technology (NIST) to ensure uniform identification of geographic entities through all federal government agencies
  • NPANXX (npa): 6-digit numbers consisting of the area code and second 3 digits of a North American dialing plan phone number

Keep these points in mind if using the Geocoding functionality (geo = true):

  1. The geocoding is slower, but provides a more accurate jurisdiction
  2. If the geocoding process fails, the entire CalcTaxes request fails
  3. PO Box addresses are not valid when using Geocoding

Note

When specifying jurisdictions outside of the United States via country/state/county/city lookup, be sure to pass the Country ISO (ctry). For example, use CAN for Canada or IND for India. If the Country ISO is not set on a foreign country, errors are generated.

See Location for more information.

Zip-Only Fallback

If the city or county name does not match and a postal code is provided, jurisdiction determination falls back to the Zip Code for transactions in the United States of America or Canada.

  • USA: 5 or 9 digit Zip Codes. For example, 95054 or 95054-1234
  • Canada: 6 byte Postal Code with or without a dash. For example, T4X-1Y6 or T4X1Y6

Full state and country names are also supported, along with the 2 character state abbreviation or 3 character ISO country code.

  • Alaska or AK
  • Quebec or QC
  • Switzerland or CHE
  • United State of America or USA

The fallback process ignores spacing and punctuation in the city and county names. For example, “CURRY’S CORNER”, AK is treated the same as “CURRYS CORNER” and “CURRYSCORNER”.

Pro Tip

Specify a PCode (pcd) for fallback when using the embedded Geocoding functionality (geo = true in a location). If geocoding fails to find the location, the PCode (pcd) is used for the jurisdiction.

United States Tax Request using Geocoding Example

Geocoding functionality is being used in this example by setting geo to true and specifying an address (addr), city (city), state (st), postal code (zip), and country (ctry).

{
  "cmpn": {
    "bscl": 0,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "doc": "TEST-VOIP INVOICE 2018.01.15:12.02 AVA",
      "cmmt": false,
      "bill": {
        "geo": true,
        "ctry": "USA",
        "st": "CA",
        "city": "Santa Clara",
        "addr": "4900 Marie P DeBartolo Way",  // Levi Stadium
        "zip": "95054"
      },
      "cust": 0,
      "lfln": false,
      "date": "2017-05-01T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 001 - VoIP/Access Charge",
          "chg": 100,
          "line": 0,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 6,
          "dbt": false,
          "adj": false
        },
        {
          "ref": "Line Item 002 - VoIP/Lines",
          "chg": 0,
          "line": 10,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 21,
          "dbt": false,
          "adj": false
        },
        {
          "ref": "Line Item 003 - VoIP/Equip Rental",
          "chg": 25,
          "line": 0,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 37,
          "dbt": false,
          "adj": false
        }
      ],
      "invm": true,
      "dtl": true,
      "summ": true,
      "opt": [
        {
          "key": "1",
          "val": "Geo Lookup Sample Line Items Invoice ABC-ZZZ"
        }
      ]
    }
  ]
}

Response

Federal, State, and County taxes are returned based upon the geocoding request.

View the Response JSON
{
  "inv": [
    {
      "doc": "TEST-VOIP INVOICE 2018.01.15:12.02 AVA",
      "itms": [
        {
          "ref": "Line Item 001 - VoIP/Access Charge",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 35.099999999999994,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "Universal Lifeline Telephone Service Charge (VoIP)",
              "exm": 64.9,
              "lns": 0,
              "min": 0,
              "pcd": 253500,
              "rate": 0.0475,
              "sur": true,
              "tax": 1.6672499999999997,
              "lvl": 1,
              "tid": 454
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 35.099999999999994,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "CA Teleconnect Fund (VoIP)",
              "exm": 64.9,
              "lns": 0,
              "min": 0,
              "pcd": 253500,
              "rate": 0.0108,
              "sur": true,
              "tax": 0.37908,
              "lvl": 1,
              "tid": 452
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 35.099999999999994,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "CA High Cost Fund A (VoIP)",
              "exm": 64.9,
              "lns": 0,
              "min": 0,
              "pcd": 253500,
              "rate": 0.0035,
              "sur": true,
              "tax": 0.12284999999999999,
              "lvl": 1,
              "tid": 450
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 35.099999999999994,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "TRS (VoIP)",
              "exm": 64.9,
              "lns": 0,
              "min": 0,
              "pcd": 253500,
              "rate": 0.005,
              "sur": true,
              "tax": 0.17549999999999996,
              "lvl": 1,
              "tid": 217
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 35.099999999999994,
              "calc": 1,
              "cat": "E-911 CHARGES",
              "cid": 7,
              "name": "E911 (VoIP)",
              "exm": 64.9,
              "lns": 0,
              "min": 0,
              "pcd": 253500,
              "rate": 0.0075,
              "sur": false,
              "tax": 0.26324999999999993,
              "lvl": 1,
              "tid": 161
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 64.9,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "FUSF (VoIP)",
              "exm": 35.099999999999994,
              "lns": 0,
              "min": 0,
              "pcd": 0,
              "rate": 0.174,
              "sur": false,
              "tax": 11.2926,
              "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": 0,
              "min": 0,
              "pcd": 0,
              "rate": 0.00302,
              "sur": false,
              "tax": 0.19599800000000003,
              "lvl": 0,
              "tid": 226
            }
          ]
        },
        {
          "ref": "Line Item 002 - VoIP/Lines"
        },
        {
          "ref": "Line Item 003 - VoIP/Equip Rental",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 25,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "District Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 390800,
              "rate": 0.0175,
              "sur": false,
              "tax": 0.43750000000000006,
              "lvl": 2,
              "tid": 4
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 25,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Sales Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 390800,
              "rate": 0.0125,
              "sur": false,
              "tax": 0.3125,
              "lvl": 2,
              "tid": 1
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 25,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Sales Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 390800,
              "rate": 0.06,
              "sur": false,
              "tax": 1.5,
              "lvl": 1,
              "tid": 1
            }
          ]
        }
      ],
      "summ": [
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 35.099999999999994,
          "calc": 1,
          "cat": "CONNECTIVITY CHARGES",
          "cid": 5,
          "name": "Universal Lifeline Telephone Service Charge (VoIP)",
          "exm": 64.9,
          "lns": 0,
          "pcd": 253500,
          "rate": 0.0475,
          "sur": true,
          "tax": 1.6672499999999997,
          "lvl": 1,
          "tid": 454
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 35.099999999999994,
          "calc": 1,
          "cat": "CONNECTIVITY CHARGES",
          "cid": 5,
          "name": "CA Teleconnect Fund (VoIP)",
          "exm": 64.9,
          "lns": 0,
          "pcd": 253500,
          "rate": 0.0108,
          "sur": true,
          "tax": 0.37908,
          "lvl": 1,
          "tid": 452
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 35.099999999999994,
          "calc": 1,
          "cat": "CONNECTIVITY CHARGES",
          "cid": 5,
          "name": "CA High Cost Fund A (VoIP)",
          "exm": 64.9,
          "lns": 0,
          "pcd": 253500,
          "rate": 0.0035,
          "sur": true,
          "tax": 0.12284999999999999,
          "lvl": 1,
          "tid": 450
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 35.099999999999994,
          "calc": 1,
          "cat": "CONNECTIVITY CHARGES",
          "cid": 5,
          "name": "TRS (VoIP)",
          "exm": 64.9,
          "lns": 0,
          "pcd": 253500,
          "rate": 0.005,
          "sur": true,
          "tax": 0.17549999999999996,
          "lvl": 1,
          "tid": 217
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 35.099999999999994,
          "calc": 1,
          "cat": "E-911 CHARGES",
          "cid": 7,
          "name": "E911 (VoIP)",
          "exm": 64.9,
          "lns": 0,
          "pcd": 253500,
          "rate": 0.0075,
          "sur": false,
          "tax": 0.26324999999999993,
          "lvl": 1,
          "tid": 161
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 64.9,
          "calc": 1,
          "cat": "CONNECTIVITY CHARGES",
          "cid": 5,
          "name": "FUSF (VoIP)",
          "exm": 35.099999999999994,
          "lns": 0,
          "pcd": 0,
          "rate": 0.174,
          "sur": false,
          "tax": 11.2926,
          "lvl": 0,
          "tid": 162
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 64.9,
          "calc": 1,
          "cat": "REGULATORY CHARGES",
          "cid": 6,
          "name": "FCC Regulatory Fee (VoIP)",
          "exm": 35.099999999999994,
          "lns": 0,
          "pcd": 0,
          "rate": 0.00302,
          "sur": false,
          "tax": 0.19599800000000003,
          "lvl": 0,
          "tid": 226
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 25,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "District Tax",
          "exm": 0,
          "lns": 0,
          "pcd": 390800,
          "rate": 0.0175,
          "sur": false,
          "tax": 0.43750000000000006,
          "lvl": 2,
          "tid": 4
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 25,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Sales Tax",
          "exm": 0,
          "lns": 0,
          "pcd": 390800,
          "rate": 0.0125,
          "sur": false,
          "tax": 0.3125,
          "lvl": 2,
          "tid": 1
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 25,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Sales Tax",
          "exm": 0,
          "lns": 0,
          "pcd": 390800,
          "rate": 0.06,
          "sur": false,
          "tax": 1.5,
          "lvl": 1,
          "tid": 1
        }
      ]
    }
  ]
}

Canadian Tax Request Example

This example sets the BillTo location (bill) to Montreal, QC.

{
  "cmpn": {
    "bscl": 0,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "doc": "TEST-VOIP INVOICE 2017.12.26:12.02 AVA",
      "cmmt": false,
      "bill": {
        "ctry": "CAN",
        "int": true,
        "geo": false,
        "city": "Montreal",
        "st": "PQ",
        "zip": "H1A-0A1"
      },
      "cust": 0,
      "lfln": false,
      "date": "2018-06-01T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 001 - VoIP/Access Charge",
          "chg": 100,
          "line": 0,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 6,
          "dbt": false,
          "adj": false
        },
        {
          "ref": "Line Item 002 - VoIP/Lines",
          "chg": 0,
          "line": 10,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 21,
          "dbt": false,
          "adj": false
        },
        {
          "ref": "Line Item 003 - VoIP/Equip Rental",
          "chg": 25,
          "line": 0,
          "sale": 1,
          "incl": false,
          "tran": 19,
          "serv": 37,
          "dbt": false,
          "adj": false
        }
      ],
      "invm": true,
      "dtl": true,
      "summ": true,
      "opt": [
        {
          "key": "1",
          "val": "Canada VoIP Sample Line Items Invoice ABC-ZZZ"
        }
      ]
    }
  ]
}

Response

Taxes returned are for Quebec (tax level lvl 1) and Canada (tax level lvl 0).

View the Response JSON
{
  "inv": [
    {
      "doc": "TEST-VOIP INVOICE 2017.12.26:12.02 AVA",
      "itms": [
        {
          "ref": "Line Item 001 - VoIP/Access Charge",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 100,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Quebec Sales Tax (QST)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 4882600,
              "rate": 0.09975,
              "sur": false,
              "tax": 9.975000000000001,
              "lvl": 1,
              "tid": 69
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 100,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Goods and Service Tax (GST)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 4482200,
              "rate": 0.05,
              "sur": false,
              "tax": 5,
              "lvl": 0,
              "tid": 66
            }
          ]
        },
        {
          "ref": "Line Item 002 - VoIP/Lines",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 4,
              "cat": "E-911 CHARGES",
              "cid": 7,
              "name": "E-911",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 4945800,
              "rate": 0.46,
              "sur": false,
              "tax": 4.6000000000000005,
              "lvl": 1,
              "tid": 10
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 4.140000000000001,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Quebec Sales Tax (QST)",
              "exm": 0.45999999999999996,
              "lns": 0,
              "min": 0,
              "pcd": 4882600,
              "rate": 0.09975,
              "sur": false,
              "tax": 0.4129650000000001,
              "lvl": 1,
              "tid": 69
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 4.140000000000001,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Goods and Service Tax (GST)",
              "exm": 0.45999999999999996,
              "lns": 0,
              "min": 0,
              "pcd": 4482200,
              "rate": 0.05,
              "sur": false,
              "tax": 0.20700000000000005,
              "lvl": 0,
              "tid": 66
            }
          ]
        },
        {
          "ref": "Line Item 003 - VoIP/Equip Rental",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 25,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Quebec Sales Tax (QST)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 4882600,
              "rate": 0.09975,
              "sur": false,
              "tax": 2.4937500000000004,
              "lvl": 1,
              "tid": 69
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 25,
              "calc": 1,
              "cat": "SALES AND USE TAXES",
              "cid": 1,
              "name": "Goods and Service Tax (GST)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 4482200,
              "rate": 0.05,
              "sur": false,
              "tax": 1.25,
              "lvl": 0,
              "tid": 66
            }
          ]
        }
      ],
      "summ": [
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 125,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Quebec Sales Tax (QST)",
          "exm": 0,
          "lns": 0,
          "pcd": 4882600,
          "rate": 0.09975,
          "sur": false,
          "tax": 12.468750000000002,
          "lvl": 1,
          "tid": 69
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 125,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Goods and Service Tax (GST)",
          "exm": 0,
          "lns": 0,
          "pcd": 4482200,
          "rate": 0.05,
          "sur": false,
          "tax": 6.25,
          "lvl": 0,
          "tid": 66
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 0,
          "calc": 4,
          "cat": "E-911 CHARGES",
          "cid": 7,
          "name": "E-911",
          "exm": 0,
          "lns": 10,
          "pcd": 4945800,
          "rate": 0.46,
          "sur": false,
          "tax": 4.6000000000000005,
          "lvl": 1,
          "tid": 10
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 4.140000000000001,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Quebec Sales Tax (QST)",
          "exm": 0.45999999999999996,
          "lns": 0,
          "pcd": 4882600,
          "rate": 0.09975,
          "sur": false,
          "tax": 0.4129650000000001,
          "lvl": 1,
          "tid": 69
        },
        {
          "max": 2147483647,
          "min": 0,
          "tchg": 4.140000000000001,
          "calc": 1,
          "cat": "SALES AND USE TAXES",
          "cid": 1,
          "name": "Goods and Service Tax (GST)",
          "exm": 0.45999999999999996,
          "lns": 0,
          "pcd": 4482200,
          "rate": 0.05,
          "sur": false,
          "tax": 0.20700000000000005,
          "lvl": 0,
          "tid": 66
        }
      ]
    }
  ]
}

Jurisdiction Determination using PCode, NPANXX, or FIPS

If you have a PCode (pcd), NPANXX (npa), or FIPS (fips) instead of an address, set these fields in BillTo (bill), From (from), or To (to) (these examples demonstrate BillTo, but the same applies to From and To):

PCode

"bill": {
  "pcd": 390800
}

NPANXX

"bill": {
  "npa": 415226
}

FIPS

"bill": {
  "fips": "0608500380"
}

See Also

Input Objects

Output Objects