Invoice Mode allows you to group multiple line items into a single invoice. The AFC Tax Engine applies any caps, thresholds, tax brackets, and tiers per invoice as a whole when in Invoice Mode (invm set to true). When Invoice Mode is turned off (invm set to false), the line items (itms) in the invoice (inv) are considered unrelated and independent, meaning caps, thresholds, tax brackets, and tiers are applied individually to each line item (itms).
Communications REST v2 provides the ability to process up to 10,000 LineItems within an invoice in Invoice Mode. Tax calculation results are summarized by jurisdiction and tax type. Optionally, the individual taxes for each line item can also be returned in the output using the Return Detail flag (dtl), but be advised that the response size may be up to a couple megabytes and may take additional time to process depending on the number of transactions in the Invoice.
Note
While the maximum number of LineItems is 10,000, it is recommended to keep the number of LineItems around 1,000 per invoice for optimal performance.
Note
It is recommended to increase the timeout of your web API calls to 10 minutes although response times are expected to be much shorter even or the largest batches.
Total Charge
Total Charge (tchg) displays the summarized charge amounts applied to the tax item from Invoice processing (invm set to true). Each entry in the summarized tax results (summ) has an individual total charge as it applies to the calculation of that specific summarized tax type and jurisdiction.
Invoice Mode Example
In this example, the three line items are processed together as one invoice because Invoice Mode (invm) is set to true. Also note that the tax calculation output is returned at both the line item detail level (dtl = true) and summary level (summ = true).
{"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","txs":[{"bill":true,"cmpl":true,"tm":0,"calc":4,"cat":"E-911 CHARGES","cid":7,"name":"San Francisco Access line Tax (VoIP)","exm":0,"lns":10,"min":0,"pcd":377300,"rate":3.27,"sur":false,"tax":32.7,"lvl":3,"tid":250}]},{"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":377200,"rate":0.0125,"sur":false,"tax":0.3125,"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":377300,"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":377300,"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":0,"calc":4,"cat":"E-911 CHARGES","cid":7,"name":"San Francisco Access line Tax (VoIP)","exm":0,"lns":10,"pcd":377300,"rate":3.27,"sur":false,"tax":32.7,"lvl":3,"tid":250},{"max":2147483647,"min":0,"tchg":25,"calc":1,"cat":"SALES AND USE TAXES","cid":1,"name":"District Tax","exm":0,"lns":0,"pcd":377200,"rate":0.0125,"sur":false,"tax":0.3125,"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":377300,"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":377300,"rate":0.06,"sur":false,"tax":1.5,"lvl":1,"tid":1}]}]}
Invoice Mode Off - Multiple LineItems Example
This example demonstrates the output results for the same multi-line CalcTaxes request, but InvoiceMode (invm) set to false. Note that the three LineItems are processed and results are returned individually. No Summary-level tax results are provided in the CalcTaxes Response even though the Return Summary flag (summ) in the request is set to true. See Displaying Tax Results for more information.
Detailed taxes (txs) for each line item are returned. However, no summarized taxes (summ) are returned since the line items are treated as individual requests not part of a larger invoice.
{"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","txs":[{"bill":true,"cmpl":true,"tm":0,"calc":4,"cat":"E-911 CHARGES","cid":7,"name":"San Francisco Access line Tax (VoIP)","exm":0,"lns":10,"min":0,"pcd":377300,"rate":3.27,"sur":false,"tax":32.7,"lvl":3,"tid":250}]},{"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":377200,"rate":0.0125,"sur":false,"tax":0.3125,"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":377300,"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":377300,"rate":0.06,"sur":false,"tax":1.5,"lvl":1,"tid":1}]}]}]}