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:
pcd
): Persisted numeric identifer for a taxing jurisdictionctry
), 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
)ctry
), State (st
), and Postal Code (zip
) are required for USA and Canada (at a minimum)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 agenciesnpa
): 6-digit numbers consisting of the area code and second 3 digits of a North American dialing plan phone numberWhen 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.
An address can be passed in a CalcTaxes
request and geocoded during the tax calculation by setting geo
= true
.
Keep these points in mind if using the Geocoding functionality (geo
= true
):
For more information, see Best Practices.
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.
Full state and country names are also supported, along with the 2 character state abbreviation or 3 character ISO country code.
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”.
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.
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", "cmmt": false, "bill": { "geo": true, "ctry": "USA", "st": "CA", "city": "Santa Clara", "addr": "4900 Marie P DeBartolo Way", "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" } ] } ]}
Federal, State, and County taxes are returned based upon the geocoding request.
{ "inv": [ { "doc": "TEST-VOIP INVOICE", "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 } ] } ]}
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", "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" } ] } ]}
Taxes returned are for Quebec (tax level lvl
1) and Canada (tax level lvl
0).
{ "inv": [ { "doc": "TEST-VOIP INVOICE", "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 } ] } ]}
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):
"bill": { "pcd": 390800}
"bill": { "npa": 415226}
"bill": { "fips": "0608500380"}