The Communications REST v2 Tax Adjustment functionality is used to perform activities such as refunds, changing a customer’s bill, or writing off un-collectable accounts.
Ways to send an Adjustment to REST v2:
- Set the Adjustment flag (
adj) totrueon the appropriate LineItem(s) - Send positive values for charge (
chg), lines (line), minutes (min), and/or locations (loc) - Set the adjustment method (
adjm) to0 - Set the discount type (
disc) - Set the Adjustment flag (
adj) tofalse - Send negative values for charge (
chg), lines (line), minutes (min), and/or locations (loc) - Set the adjustment method (
adjm) to0 - Set the discount type (
disc)
Note
Adjustment transactions are run independently of any other invoice, meaning that there is no connection between the transactions. Be mindful of what has been submitted to avoid duplicate credits to your customers, etc. The Reporting tool within Customer Portal can be used to help identify the transactions and adjustments already processed.
Adjustment Method
The use of Adjustment Method (adjm) has been deprecated. This field should always be defaulted to 0.
Discount Type
Set the Discount Type (disc) to one of the values listed below. If discounts do not apply or you are unsure, set the field to 0.
Note
Using a Discount Type other than 0 None may result in a $0.00 tax calculation, because some jurisdictions don’t allow tax refunds for other discount types.
Discounts may or may not be taxed within each state. When a discount is taxed, the customer receives a tax benefit commensurate with the amount of the discount (i.e., if the customer gets $5 off on a transaction subject to a 5% tax, the customer pays $0.25 less in tax than they would have).
When a discount is not taxed, the customer receives no tax benefit from the discount. Whether a discount is taxed or not depends on the type of discount and the rules in the particular tax jurisdiction.| Name | Value | Description |
|---|---|---|
| None (default) | 0 | Not Defined, engine will return negative tax.​ |
| Retail Product | 1 | Promotional pricing, customer discounts and/or coupons that result in a reduction of price in goods |
| Manufacturer Rebate | 2 | A credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer |
| Account Level | 3 | A deduction in the tax amount based on reasons such as bad debt write offs or billing corrections. |
| Subsidized | 4 | Government credits such as for a telephone service where the provider provides a service to a lifeline eligible customer for a subscriber line charge. |
| Goodwill | 5 | A credit applied to a customer's invoice for the purpose of good will, for example compensation for a service outage. |
Retail Product Example Scenario
A customer has voice mail and is charged a monthly recurring charge of $6.00/month. The customer buys a second line and gets voice mail free for a month. The billing system will make separate calls to REST v2 for the monthly recurring charge of $6.00 and the discount of -$6.00. Both transactions will be represented by the same tax category, but the billing system will send an additional value on the discount transaction indicating that it is a Retailer discount.
The $6.00 charge for voice mail generates $0.32 in state sales tax. For the -$6.00 discount, REST v2 determines that the state allows a full tax credit on Retailer Discounts and generates -$0.32 in state sales tax. The offsetting tax amounts are presumably netted together in the tax summary on the customer’s bill. Whether the charge and discount amounts are netted on the customer’s bill is up to the billing system, and does not affect the tax calculation or the presentation of tax on the bill.
Manufacturer Product Example Scenario
A customer buys a satellite dish for $300.00 and receives a $50.00 rebate (discount) from the satellite company. The billing system will make separate calls to REST v2 for the dish charge of $300.00 and the discount of -$50.00. Both transactions will be represented by the same tax category, but the billing system will send an additional value on the discount transaction indicating that it is a Manufacturer discount. The $300.00 charge for the satellite dish generates $15.90 in state sales tax. For the -$50.00 discount, REST v2 determines that the state does not allow any tax credit on Manufacturer Discounts and generates $0.00 in state sales tax. The offsetting tax amounts are presumably netted together in the tax summary on the customer’s bill. Whether the charge and discount amounts are netted on the customer’s bill is up to the billing system, and does not affect the tax calculation or the presentation of tax on the bill.
Account Level Scenario​
A customer has an issue on their invoice and the company provides a credit on their invoice for a previous month to correct the amount. An example is a customer was charged $20.00 for their subscription services and should have only been charged $10.00. Taxes were calculated on the full $20.00 in the prior month. This credit will generate a tax credit for the amount overcharged based on the $10.00 credit.
Subsidized Example Scenario
A Lifeline customer purchases local exchange service. Local exchange service typically includes a fee for a subscriber line charge of $6.50. Lifeline customers receive an offsetting credit for $6.50. The company still has $6.50 in revenue and may need to collect sales tax on the entire amount. The company is prohibited from drawing on the federal government fund to pay for the tax on any amount due, so the customer must pay all of the applicable tax.
Goodwill Scenario
A customer calls to complain about a service outage. The company provides a credit of $10.00 for amount of time their service was out which will apply to their next months invoice. This type of credit will typically result in a negative tax amount as a response.
Adjustment Example using Adjustment Flag
In this example, the adjustment flag (adj) is set to true on all three line item included in the invoice and the charge amounts (chg) are positive values. Adjustment method (adjm) is explicitly set to 0 on Line Items 001 and 003, while allowed to default on Line Item 002. Discount Type (disc) is set to 0 for Line Item 001, 1 for Line Item 002, and 5 for Line Item 003.
{ "cmpn": { "bscl": 0, "svcl": 0, "fclt": false, "frch": false, "reg": false }, "inv": [ { "doc": "ADJUSTMENT FLAG EXAMPLE", "cmmt": false, "bill": { "cnty": "San Francisco", "ctry": "USA", "int": true, "geo": false, "city": "San Francisco", "st": "CA", "zip": "94102" }, "cust": 0, "lfln": false, "date": "2017-05-01T12:00:00Z", "itms": [ { "ref": "Line Item 001 - Adjustment with Discount Type 0", "chg": 100, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 6, "dbt": false, "adj": true, "adjm": 0, "disc": 0 }, { "ref": "Line Item 002 - Adjustment with Discount Type 1", "chg": 0, "line": 10, "sale": 1, "incl": false, "tran": 19, "serv": 21, "dbt": false, "adj": true, "disc": 1 }, { "ref": "Line Item 003 - Adjustment with Discount Type 5", "chg": 25, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 37, "dbt": false, "adj": true, "adjm": 0, "disc": 5 } ], "invm": true, "dtl": true, "summ": true } ]}Response
Notice the negative exempt sale amounts (exm) and tax amounts (tax), indicating the credit back to your customer.
{ "inv": [ { "doc": "ADJUSTMENT FLAG EXAMPLE", "itms": [ { "ref": "Line Item 001 - Adjustment with Discount Type 0", "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 - Adjustment with Discount Type 1", "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 - Adjustment with Discount Type 5" } ], "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 } ] } ]}Adjustment Example using Negative Amounts
In this example, the adjustment flag (adj) is set to false on all three line item included in the invoice and the charge amounts (chg) are set to negative values, indicating the need for an adjustment. Adjustment method (adjm) is explicitly set to 0 on Line Items 001 and 003, while allowed to default on Line Item 002. Discount Type (disc) is set to 0 for Line Item 001, 1 for Line Item 002, and 5 for Line Item 003.
{ "cmpn": { "bscl": 0, "svcl": 0, "fclt": false, "frch": false, "reg": false }, "inv": [ { "doc": "NEGATIVE AMOUNTS ADJUSTMENT EXAMPLE", "cmmt": false, "bill": { "cnty": "San Francisco", "ctry": "USA", "int": true, "geo": false, "city": "San Francisco", "st": "CA", "zip": "94102" }, "cust": 0, "lfln": false, "date": "2017-05-01T12:00:00Z", "itms": [ { "ref": "Line Item 001 - Adjustment with Discount Type 0", "chg": -100, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 6, "dbt": false, "adj": false, "adjm": 0, "disc": 0 }, { "ref": "Line Item 002 - Adjustment with Discount Type 1", "chg": 0, "line": -10, "sale": 1, "incl": false, "tran": 19, "serv": 21, "dbt": false, "adj": false, "disc": 1 }, { "ref": "Line Item 003 - Adjustment with Discount Type 5", "chg": -25, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 37, "dbt": false, "adj": false, "adjm": 0, "disc": 5 } ], "invm": true, "dtl": true, "summ": true } ]}Response
Notice the negative exempt sale amounts (exm) and tax amounts (tax), indicating the credit back to your customer.
{ "inv": [ { "doc": "NEGATIVE AMOUNTS ADJUSTMENT EXAMPLE", "itms": [ { "ref": "Line Item 001 - Adjustment with Discount Type 0", "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 - Adjustment with Discount Type 1", "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 - Adjustment with Discount Type 5" } ], "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 } ] } ]}