Chapter 4.3.21 - Request Config

Communications REST v2 allows you to control the response output via the Request Config object (cfg).

There are several configuration options available:

  • retnb: Return non-billable taxes
  • retext: Return extended data in the response
  • incrf: Return reporting information in the response

Return Non-Billable Taxes

The retnb flag allows you to control if non-billable taxes are returned in the response. If this field is not provided, it defaults to the account-level setting.

  • true: Return non-billable taxes. Setting retnb to true overrides the account-level setting
  • false: Don't return non-billable taxes

Return Extended Data

The retext flag indicates if you want to see a number of extended fields in the detailed tax result:

  • When taxes are returned:
    • Taxing PCode (taxpcd): PCode representing taxing jurisdiction
    • User Exempt (usexm): Flag indicating if the tax has been exempted by the user via Exemptions (exms)
    • Is No Tax Transaction (notax): Flag indicating that the transaction processed successfully but returned no taxes
    • Transaction Type (trans): Transaction type use to calculate tax. For bundles, this field shows the specific bundled item transaction type
    • Service Type (svc): Service type use to calculate tax. For bundles, this field shows the specific bundled item transaction type
    • Charge (chg): Charge used to calculate tax. For bundles, this field shows the percentage of the charge applied to the bundled item. For tax inclusive calls, this field shows the calculated charge
  • When no taxes are returned:
    • Billable (bill): Always returns false
    • Tax Name (name): Always returns "NO TAX"
    • Reporting PCode (pcd) and Taxing PCode (taxpcd): Reporting PCode and Taxing PCode are always the same value
      • If the location provided is an unsupported country, the Reporting PCode (pcd) and Taxing PCode (taxpcd) are both set to the Unsupported Country PCode (5190000)
    • Tax Amount (tax): Always returns 0
    • Tax Type ID (tid): Always returns 0
    • User Exempt (usexm): Always returns false
    • Is No Tax Transaction (notax): Always returns true
    • Transaction Type (trans): Transaction type use to calculate tax. For bundles, this field shows the specific bundled item transaction type
    • Service Type (svc): Service type use to calculate tax. For bundles, this field shows the specific bundled item transaction type
    • Charge (chg): Charge used to calculate tax. For bundles, this field shows the percentage of the charge applied to the bundled item. For tax inclusive calls, this field shows the calculated charge

Reporting Information

The incrf flag enables the return of the Reporting Information object (incrf) in the CalcTaxes response.

Populate some or all of these reporting information fields on the invoice (inv) to see the information in the response and in Explorer Reporting:

  • Account Reference (acct)
  • Customer Reference (custref)
  • Invoice Number Reference (invn)
  • Bill Cycle Reference (bcyc)
  • Currency Code (ccycd)

All of the reporting information fields populated on the invoice (inv), as well as the Currency Description (ccydesc) are returned in Reporting Information object (incrf).

Line Item Reporting Information

Reporting fields are available for use on the line item (itms). Just like on the invoice, populate these reporting information fields on the invoice (itms) to see the information in the response and in Explorer Reporting:

  • Line Item Reference (ref)
  • General Ledger Reference (glref)

Request Config Example - All Options On

In this example, all of the Request Config configuration options are set to true. Line Item Reference (ref) and General Ledger Reference (glref) are included on the line item (itms).

{
  "cfg": {
  	"retnb": true,
	  "retext": true,
	  "incrf": true
  },
  "cmpn": {
    "bscl": 1,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "bill": {
        "pcd": 534300
      },
      "cust": 1,
      "lfln": false,
      "date": "2018-05-15T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 1",
          "chg": 0,
          "line": 10,
          "sale": 1,
          "tran": 13,
          "serv": 6,
          "glref": "General Ledger Reference"
        }
      ],
      "invm": false,
      "dtl": true,
      "summ": false,
      "acct": "Account Reference",
      "custref": "Customer Reference",
      "invn": "Invoice Number Reference",
      "bcyc": "Bill Cycle Reference",
      "ccycd": "USD"
    }
  ]
}

Response

Non-billable tax (bill = false) Tax Type ID (tid) 232 is returned in the response. Each detailed tax result (txs) returns the extended tax data. Reporting Information (incrf) is also included.

Notice that the General Ledger Reference (glref) is not returned on the line item (itms).

View the Response JSON
{
  "inv": [
    {
      "itms": [
        {
          "ref": "Line Item 1",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "GROSS RECEIPTS TAXES",
              "cid": 3,
              "name": "Statutory Gross Receipts (Wireless)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534300,
              "taxpcd": 534300,
              "rate": 0.0252,
              "sur": false,
              "tax": 0.00042001,
              "lvl": 1,
              "tid": 75,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 2,
              "cat": "E-911 CHARGES",
              "cid": 7,
              "name": "E911 (Wireless)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534200,
              "taxpcd": 534300,
              "rate": 0.4,
              "sur": false,
              "tax": 0.4,
              "lvl": 1,
              "tid": 44,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "COMMUNICATIONS SERVICES TAX",
              "cid": 10,
              "name": "Communications Service Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534300,
              "taxpcd": 534300,
              "rate": 0.0587,
              "sur": false,
              "tax": 0.00097835,
              "lvl": 3,
              "tid": 64,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "COMMUNICATIONS SERVICES TAX",
              "cid": 10,
              "name": "Communications Service Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534200,
              "taxpcd": 534300,
              "rate": 0.0492,
              "sur": false,
              "tax": 0.00082002,
              "lvl": 1,
              "tid": 64,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "Fed USF Cellular",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 0,
              "taxpcd": 534300,
              "rate": 0.184,
              "sur": false,
              "tax": 0,
              "lvl": 0,
              "tid": 55,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 2,
              "cat": "REGULATORY CHARGES",
              "cid": 6,
              "name": "FCC Regulatory Fee (Wireless)",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 0,
              "taxpcd": 534300,
              "rate": 0.016667,
              "sur": false,
              "tax": 0.016667,
              "lvl": 0,
              "tid": 170,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            },
            {
              "bill": false,
              "cmpl": true,
              "tm": 0,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "Telecommunications Relay Surcharge (Cellular)",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 0,
              "taxpcd": 534300,
              "rate": 0.02289,
              "sur": false,
              "tax": 0,
              "lvl": 0,
              "tid": 232,
              "usexm": false,
              "notax": false,
              "trans": 13,
              "svc": 6,
              "chg": 0
            }
          ]
        }
      ],
      "incrf": {
        "acct": "Account Reference",
        "custref": "Customer Reference",
        "invn": "Invoice Number Reference",
        "bcyc": "Bill Cycle Reference",
        "ccycd": "USD",
        "ccydesc": "US Dollar"
      }
    }
  ]
}

Request Config Example - All Options Off

In this example, all of the Request Config configuration options are set to false.

{
  "cfg": {
  	"retnb": false,
	  "retext": false,
	  "incrf": false
  },
  "cmpn": {
    "bscl": 1,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "bill": {
        "pcd": 534300
      },
      "cust": 1,
      "lfln": false,
      "date": "2018-05-15T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 1",
          "chg": 0,
          "line": 10,
          "sale": 1,
          "tran": 13,
          "serv": 6,
          "glref": "General Ledger Reference"
        }
      ],
      "invm": false,
      "dtl": true,
      "summ": false,
      "acct": "Account Reference",
      "custref": "Customer Reference",
      "invn": "Invoice Number Reference",
      "bcyc": "Bill Cycle Reference",
      "ccycd": "USD"
    }
  ]
}

Response

Non-billable tax (bill = false) Tax Type ID (tid) 232 is not returned in the response. The detailed tax results (txs) don’t include the extended tax data. Reporting Information (incrf) is not returned.

View the Response JSON
{
  "inv": [
    {
      "itms": [
        {
          "ref": "Line Item 1",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "GROSS RECEIPTS TAXES",
              "cid": 3,
              "name": "Statutory Gross Receipts (Wireless)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534300,
              "rate": 0.0252,
              "sur": false,
              "tax": 0.00042001,
              "lvl": 1,
              "tid": 75
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 2,
              "cat": "E-911 CHARGES",
              "cid": 7,
              "name": "E911 (Wireless)",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534200,
              "rate": 0.4,
              "sur": false,
              "tax": 0.4,
              "lvl": 1,
              "tid": 44
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "COMMUNICATIONS SERVICES TAX",
              "cid": 10,
              "name": "Communications Service Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534300,
              "rate": 0.0587,
              "sur": false,
              "tax": 0.00097835,
              "lvl": 3,
              "tid": 64
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0.016667,
              "calc": 1,
              "cat": "COMMUNICATIONS SERVICES TAX",
              "cid": 10,
              "name": "Communications Service Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 534200,
              "rate": 0.0492,
              "sur": false,
              "tax": 0.00082002,
              "lvl": 1,
              "tid": 64
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 1,
              "cat": "CONNECTIVITY CHARGES",
              "cid": 5,
              "name": "Fed USF Cellular",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 0,
              "rate": 0.184,
              "sur": false,
              "tax": 0,
              "lvl": 0,
              "tid": 55
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 0,
              "calc": 2,
              "cat": "REGULATORY CHARGES",
              "cid": 6,
              "name": "FCC Regulatory Fee (Wireless)",
              "exm": 0,
              "lns": 10,
              "min": 0,
              "pcd": 0,
              "rate": 0.016667,
              "sur": false,
              "tax": 0.016667,
              "lvl": 0,
              "tid": 170
            }
          ]
        }
      ]
    }
  ]
}

Request Config Example - No Tax Extended Data

In this example, only the retext Request Config configuration option is set to true. The transaction returns no taxes. The Bill To location (bill) is set to an unsupported country.

{
  "cfg": {
    "retext": true
  },
  "cmpn": {
    "bscl": 1,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "bill": {
        "ctry": "ALA"
      },
      "cust": 1,
      "lfln": false,
      "date": "2018-05-15T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 1",
          "chg": 100,
          "line": 0,
          "sale": 1,
          "tran": 14,
          "serv": 15
        }
      ],
      "invm": false,
      "dtl": true,
      "summ": false,
      "acct": "Account Reference",
      "custref": "Customer Reference",
      "invn": "Invoice Number Reference",
      "bcyc": "Bill Cycle Reference",
      "ccycd": "USD"
    }
  ]
}

Response

No taxes are returned but the no tax extended data information is returned. The Billable flag (bill) is false) even though retext is false. The Tax Name (name) reflects "NO TAX". The Reporting PCode (pcd) and Taxing PCode (taxpcd) both return the Unsupported Country PCode (5190000).

View the Response JSON
{
  "inv": [
    {
      "itms": [
        {
          "ref": "Line Item 1",
          "txs": [
            {
              "bill": false,
              "name": "NO TAX",
              "pcd": 5190000,
              "taxpcd": 5190000,
              "tax": 0,
              "tid": 0,
              "usexm": false,
              "notax": true,
              "trans": 14,
              "svc": 15,
              "chg": 100
            }
          ]
        }
      ]
    }
  ]
}

See Also

Input Objects

Output Objects