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
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
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.
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","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"}]}]}
Response
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}]}]}
Canadian Tax Request Example
This example sets the BillTo location (bill) to Montreal, QC.
{"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}]}]}
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):
