Chapter 4.3.6 - Tax Override
The Communications REST v2 Tax Override object (ovr) allows you to change the rate of a tax in the AFC tax engine within the context of a CalcTaxes request.
Note
We recommend using a client profile with a custom override file applied even though the CalcTaxes request gives you the flexibility to input Override information for each transaction. This results in better performance from the AFC Tax Engine because your override settings are cached before tax calculation begins.
Note
A Tax Override (ovr) can only be applied to a tax type (tid) that applies to the specified location (loc) and tax level (lvl).
Tax Override Fields
Tax Override fields used for overriding a tax type rate:
| Key | Name | Definition |
|---|---|---|
loc | Location | Override location information There are several ways to input location information. See the Location for more information |
scp | Scope | Scope to which the override is applied: Country, State, County, or City |
tid | Tax Type ID | Tax Type to override. A list of Tax Type IDs is available in the /api/v2/afc/taxtype/{taxType} endpoint |
lvl | Tax Level ID | Tax Level to override
|
lvlExm | Level Exemptible | Indicates if the tax can be exempted using level exemptions
|
brkt | Tax Bracket | List of tax brackets for the override |
Scope
Scope (scp) defines the tax level in which the taxes will be considered as candidates for override:
0: Country1: State2: County3: City
Tax Bracket
Tax Bracket sets the rate and bracket information for the override.
| Key | Name | Definition |
|---|---|---|
rate | Tax Rate | Tax rate for this tax bracket
|
rate | Max Base | The maximum base that this rate applies to
|
Tax Override Example
This request contains these overrides:
- Tax Type (
tid) 162 is overridden to a 0 rate (ratewithin tax bracket (brkt)) for all tax brackets (maxwithin tax bracket (brkt) set to the "unlimited" value (2147483647)) for all jurisdictions within the USA (ctrywithin location (loc)) - Tax Type (
tid) 163 is overridden to a 0.195 rate (ratewithin tax bracket (brkt)) for all tax brackets (maxwithin tax bracket (brkt) set to the "unlimited" value (2147483647)) for all jurisdictions within the USA (ctrywithin location (loc))
{ "cmpn": { "bscl": 0, "svcl": 0, "fclt": false, "frch": false, "reg": false }, "inv": [ { "doc": "TEST-VOIP RATE OVERRIDE INVOICE", "cmmt": false, "bill": { "cnty": "New York", "ctry": "USA", "int": true, "geo": false, "city": "New York", "st": "NY", "zip": "10001" }, "cust": 0, "lfln": false, "date": "2018-05-01T12:00:00Z", "itms": [ { "ref": "Line Item 001 - VoIP/Interstate Usage", "chg": 100, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 49, "dbt": false, "adj": false }, { "ref": "Line Item 002 - VoIP/International Usage", "chg": 100, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 51, "dbt": false, "adj": false } ], "invm": true, "dtl": true, "summ": true, "opt": [ { "key": "1", "val": "VoIP Sample Rate Override - Remove 162 and add 163" } ] } ], "ovr": [ { "loc": { "ctry": "USA" }, "scp": 0, "tid": 162, "lvl": 0, "lvlExm": true, "brkt": [ { "rate": 0, "max": 2147483647 } ] }, { "loc": { "ctry": "USA" }, "scp": 0, "tid": 163, "lvl": 0, "lvlExm": true, "brkt": [ { "rate": 0.195, "max": 2147483647 } ] } ]}Response
Tax Type (tid) 163 uses the overridden rate (rate) of 0.195 for all line items (txs) and the summarized taxes (summ). Tax Type 162 is not returned as a tax for this transaction since the rate has been overridden to 0.
View the Response JSON
{ "inv": [ { "doc": "TEST-VOIP RATE OVERRIDE INVOICE", "itms": [ { "ref": "Line Item 001 - VoIP/Interstate Usage", "txs": [ { "bill": true, "cmpl": true, "tm": 123.55782948940758, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "NY MCTD 186c", "exm": 0, "lns": 0, "min": 0, "pcd": 2604000, "rate": 0.00595, "sur": true, "tax": 0.7351690854619752, "lvl": 2, "tid": 27 }, { "bill": true, "cmpl": true, "tm": 123.55794753937319, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "Excise Tax", "exm": 0, "lns": 0, "min": 0, "pcd": 2502500, "rate": 0.025, "sur": true, "tax": 3.08894868848433, "lvl": 1, "tid": 5 }, { "bill": true, "cmpl": true, "tm": 100.195998, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF", "exm": 0, "lns": 0, "min": 0, "pcd": 0, "rate": 0.195, "sur": false, "tax": 19.53821961, "lvl": 0, "tid": 163 }, { "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/International Usage", "txs": [ { "bill": true, "cmpl": true, "tm": 123.68852798255152, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "NY MCTD 186c", "exm": 0, "lns": 0, "min": 0, "pcd": 2604000, "rate": 0.00595, "sur": true, "tax": 0.7359467414961818, "lvl": 2, "tid": 27 }, { "bill": true, "cmpl": true, "tm": 123.68865037347913, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "Excise Tax", "exm": 0, "lns": 0, "min": 0, "pcd": 2502500, "rate": 0.025, "sur": true, "tax": 3.0922162593369786, "lvl": 1, "tid": 5 }, { "bill": true, "cmpl": true, "tm": 100.302, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF", "exm": 0, "lns": 0, "min": 0, "pcd": 0, "rate": 0.195, "sur": false, "tax": 19.55889, "lvl": 0, "tid": 163 }, { "bill": true, "cmpl": true, "tm": 100, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 0, "lns": 0, "min": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.302, "lvl": 0, "tid": 226 } ] } ], "summ": [ { "max": 2147483647, "min": 0, "tchg": 247.2463574719591, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "NY MCTD 186c", "exm": 0, "lns": 0, "pcd": 2604000, "rate": 0.00595, "sur": true, "tax": 1.471115826958157, "lvl": 2, "tid": 27 }, { "max": 2147483647, "min": 0, "tchg": 247.24659791285234, "calc": 1, "cat": "EXCISE TAXES", "cid": 4, "name": "Excise Tax", "exm": 0, "lns": 0, "pcd": 2502500, "rate": 0.025, "sur": true, "tax": 6.181164947821308, "lvl": 1, "tid": 5 }, { "max": 2147483647, "min": 0, "tchg": 200.497998, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF", "exm": 0, "lns": 0, "pcd": 0, "rate": 0.195, "sur": false, "tax": 39.097109610000004, "lvl": 0, "tid": 163 }, { "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": 100, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 0, "lns": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.302, "lvl": 0, "tid": 226 } ] } ]}