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
  • 0: Federal
  • 1: State
  • 2: County
  • 3: City
lvlExm Level Exemptible Indicates if the tax can be exempted using level exemptions
  • true: Level Exemptible
  • false: Not Level Exemptible
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: Country
  • 1: State
  • 2: County
  • 3: 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
  • Value cannot be negative
  • Value must be between 0 and 1 for rated (percentage) taxes
  • Value may be greater than 1 for per-line or fixed rate taxes
rate Max Base The maximum base that this rate applies to
  • Set Max Base to the max amount for the bracket if applicable
  • Use 2147483647 for "unlimited" or if the tax does not use brackets


Tax Override Example

This request contains these overrides:

  1. Tax Type (tid) 162 is overridden to a 0 rate (rate within tax bracket (brkt)) for all tax brackets (max within tax bracket (brkt) set to the "unlimited" value (2147483647)) for all jurisdictions within the USA (ctry within location (loc))
  2. Tax Type (tid) 163 is overridden to a 0.195 rate (rate within tax bracket (brkt)) for all tax brackets (max within tax bracket (brkt) set to the "unlimited" value (2147483647)) for all jurisdictions within the USA (ctry within location (loc))
{
  "cmpn": {
    "bscl": 0,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "doc": "TEST-VOIP RATE OVERRIDE INVOICE 2018.05.01:12.00 AVA",
      "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 2018.05.01:12.00 AVA",
      "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
        }
      ]
    }
  ]
}

See Also

Input Objects

Output Objects

Helpful Pages