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 taxesretext: Return extended data in the responseincrf: 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. Settingretnbtotrueoverrides the account-level settingfalse: 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
- Taxing PCode (
- When no taxes are returned:
- Billable (
bill): Always returnsfalse - 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)
- If the location provided is an unsupported country, the Reporting PCode (
- Tax Amount (
tax): Always returns0 - Tax Type ID (
tid): Always returns0 - User Exempt (
usexm): Always returnsfalse - Is No Tax Transaction (
notax): Always returnstrue - 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
- Billable (
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) - Note that General Ledger Reference (
glref) isn't returned in the response, but can be found in Explorer Reporting
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).
{ "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.
{ "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).
{ "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 } ] } ] } ]}