Communications REST v2 takes the transaction as a whole and returns taxes based on the information provided.
Each transaction contains:
A product (defined by the Transaction/Service pair) can return different taxes, or no taxes, depending on the selections made. For example, setting these details on a transaction returns 0 taxes:
- Customer Type (
cust): Residential (0) - Jurisdiction (
bill): Richmond, OH - Transaction/Service Pair (
tran and serv): Internet/WEB Hosting (5/29)
But by changing Customer Type to Business (cust to 1), State and Country Sales Tax is returned. It is imperative that the transaction information is set correctly to get the proper taxes back.
Company (Seller) Data
Company data defines the company or seller. Set these keys in CompanyData.
For more information, see CompanyData.
| Name | Key | Description |
| Business Class | bscl | Specifies whether the business making the transaction is an Incumbent Local Exchange Company (ILEC) or not an ILEC Only impacts Communications transactions in certain jurisdictions, such as Oregon | Value | Option | Description | 0 | ILEC | Engaged in selling services over company-owned lines and equipment | 1 | Not an ILEC | Engaged in selling services competing with an incumbent provider | Use Not an ILEC if neither class applies |
| Service Class | svcl | Delineates the primary activity of an organization as Local Service or Long Distance Only impacts Communications transactions in certain jurisdictions, such as New York | Value | Option | Description | 0 | Primary Local | Carriers vending their services with over 50% of the gross business activities in Local Service revenue | 1 | Primary Long Distance | Carriers vending their services with over 50% of the gross business activities in Long Distance revenue | |
| Facilities | fclt | Specifies whether the transaction is sold over tangible facilities controlled by the seller. In some jurisdictions, tax outcomes vary depending on whether the service is delivered over infrastructure controlled by the seller | Value | Option | Description | true | Facilities Based | Seller delivering the service owns or controls the facilities used to provide the service | false | Non-Facilities Based | Carrier does not own the facilities | |
| Franchise | frch | Indicates that the seller provides services sold pursuant to a franchise agreement between the carrier and the jurisdiction | Value | Option | Description | true | Franchise | Seller has a franchise agreement with the jurisdiction | false | Not a Franchise | Franchise fees and taxes do not apply to seller | |
| Regulated | reg | Specifies if the company and its services are regulated by the regulatory commission in the state of the service | Value | Option | Description | true | Regulated | Company is rate-regulated | false | Not Regulated | Company is not rate-regulated | All transactions should be set to false unless the seller is registered with the state regulatory commission as a rate-regulated, incumbent provider |
| Company Identifier | idnt | Used for reporting purposes and does not impact taxation. The typical use for this field is to distinguish transactions for different companies or other delineations |
| Exclusions | excl | The Exclusions object allows you to specify the exclusions that apply to the transaction |
Customer (Buyer) Data
Customer data defines the customer or buyer. Set these keys in:
| Name | Key | Description |
| Customer Type | cust | Specifies the type of customer involved in the transaction Set on the invoice but can be overridden on a line item | Value | Option | Description | 0 | Residential | Transactions made by the customer for home use | 1 | Business | Transactions made at a place of business | 2 | Senior Citizen | Transactions made by the customer who meets the jurisdiction requirements to be considered a senior citizen and qualify for senior citizen tax breaks | 3 | Industrial | Transactions made at an industrial business | |
| Lifeline | lfln | Indicates if the customer is a Lifeline participant Set on the invoice but can be overridden on the line item | Value | Option | Description | true | Lifeline Participant | Turns off the calculation of taxes that are not collected from Lifeline recipients | false | Not a Lifeline Participant | Collects all taxes | |
| Incorporated | int | Specifies whether the customer is involved in this transaction inside or outside of the Local level of the jurisdiction | Value | Option | Description | true | Incorporated | Jurisdiction is inside an incorporated location | false | Unincorporated | Jurisdiction is outside an incorporated location. This option usually results in no local taxes returned | Use true if unsure |
| Exemptions | exms | The Exemptions object allows you to specify the exemptions that apply to the transaction |
Transaction Data
Transaction data defines the transaction:
- Where the transaction takes place
- What is being be taxed
- How to process the transaction (is the transaction an adjustment?)
- Other details, such as how the results are to be returned
Set these keys in Invoice or LineItem.
Transactions can also be customized through Tax Overrides and Safe Harbor Overrides.
Invoice Keys
For more information, see Invoice.
| Name | Key | Description |
| Document Code | doc | Identifies a single or group of transactions, quotes, or invoices in the calling system. This is a user-defined field limited to 150 characters Document Code must be set if Commit is true |
| Commit | cmmt | Specifies if the Document Code should be committed as soon as the tax calculation is processed - If Document Code is provided but Commit is
null, Commit is set to false - If Commit is
true, Document Code must be set | Value | Option | Description | true | Committed | Document Code is committed | false | Uncommitted | Document Code is not committed or is uncommitted if previously committed and still within the current reporting period | |
| BillTo Jurisdiction | bill | Identifies the location to be billed. BillTo is set on the invoice but can be overridden on the line item |
| Invoice Date | date | Date applied to the transaction or invoice. Normally set to the bill date, invoice date, or call date (as applicable) Set on the invoice but can be overridden on the line item |
| Invoice Mode | invm | Indicates if all line items within an invoice should be processed individually or as one invoice | Value | Option | Description | true | Invoice Mode | Line items are part of a single invoice | false | Not Invoice Mode | Line items are unrelated | |
| Return Detail | dtl | Indicates if individual line item taxes should be included in response | Value | Option | Description | true | Return Detailed Taxes | Return line item level tax results | false | Don't Return Detailed Taxes | Don't return line item level tax results | ReturnDetail, ReturnSummary, or both must be set to true |
| Return Summary | summ | Indicates if the summarized taxes for the invoice should be included in the response | Value | Option | Description | true | Return Summary Taxes | Return summarized tax results when InvoiceMode (invm is true | false | Don't Return Summary Taxes | Don't return summarized tax results | ReturnDetail, ReturnSummary, or both must be set to true |
| Optional Fields | opt | Optional reporting fields useful in reporting. Optional Fields do not impact taxation |
| Account Reference | acct | Account Reference field for use in reporting |
| Customer Reference | custref | Customer Reference field for use in reporting |
| Invoice Number Reference | invn | Invoice Number Reference field for use in reporting |
| Bill Cycle Reference | bcyc | Bill Cycle Reference field for use in reporting |
| Billing Period | bpd | Specifies the billing period for the invoice |
| Currency Code | ccycd | Currency code for the invoice. Example: use USD for United States Dollar |
LineItem Keys
For more information, see LineItem.
| Name | Key | Description |
| Reference Code | ref | Reference ID for the line item |
| Origination/Ship From Jurisdiction | from | Location for the origination point. If null, the BillTo location is used |
| Termination/Ship To Jurisdiction | to | Location for the destination point. If null, the BillTo location is used |
| Charge | chg | Specifies the amount of the transaction to be taxed. For Tax Inclusive transactions, Charge specifies the desired total (base charge + taxes) Defaults to 0 if not set |
| Lines | line | Specifies the line count When local service is provided, Lines should be populated with the number of lines the customer subscribes to. This information is used to generate per-line taxes usually associated with local E911 charges, local telecommunications relay service taxes, and other assorted taxes Defaults to 0 if not set |
| Locations | loc | Specifies the number of customer locations Defaults to 0 if not set |
| Minutes | min | Specifies the length of a phone call Used in the generation of taxes that are specified as per-minute flat fees in some taxing jurisdictions. Minutes is a double so any seconds added should be in decimal format. For example, use 20.5 for 20 minutes and 30 seconds Defaults to 0 if not set |
| Sale Type | sale | Indicates if the transaction retail or wholesale | Value | Option | Description | 0 | Wholesale | Specifies that the transaction is a sale to another company that will resell the product or service to a consumer | 1 | Retail | Specifies that the transaction is a sale to an end user | 2 | Consumed | Sales and Use only Specifies that the transaction is for an item that is consumed directly | 3 | Vendor Use | Sales and Use only Specifies that the transaction is for an item that is subject to vendor use tax | |
| Private Line Split | plsp | Percentage split for a private line transaction Set as a decimal and defaults to 0 if not set |
| Tax Inclusive | incl | Indicates if the charge for the line item includes tax | Value | Option | Description | true | Tax Inclusive | Taxes are included in the Line Item charge | false | Not Tax Inclusive | Taxes not included in the Line Item charge | |
| Proration | pror | Percentage allocation for a pro-rated calculation of fixed taxes Set as a decimal and defaults to 0 if not set |
| Pro-rated Adjustment Type | proadj | Defines the adjustment type for pro-rated credit or adjustment calculations | Value | Option | Description | 0 | Default | Default handling of non-proratable fixed taxes | 1 | Return non-proratable fixed taxes | Return non-proratable fixed taxes in the response | 2 | Don't return non-proratable fixed taxes | Don't return non-proratable fixed taxes in the response | |
| Transaction Type | tran | Transaction Type ID of the service being taxed Use the /api/v2/afc/tspairs Lookups endpoint for a list of transaction type IDs |
| Service Type | serv | Service Type ID of the service being taxed Use the /api/v2/afc/tspairs Lookups endpoint for a list of service type IDs |
| Debit | dbt | Indicates if the transaction is prepaid | Value | Option | Description | true | Debit | Perform a debit call tax calculation | false | Not Debit | Debit does not apply | Set Debit to true only if you are a prepaid seller |
| Adjustment | adj | Indicates if this line item is a credit or adjustment | Value | Option | Description | true | Adjustment | Is a credit/adjustment | false | Not an Adjustment | Not a credit or adjustment | |
| Adjustment Method | adjm | Always set to 0. The use of this field has been deprecated |
| Discount Type | disc | Identifies the discount type for an adjustment | Value | Option | Description | 0 | None | Discount Type not applicable | 1 | Retail Product | An amount subtracted from the original price to arrive at a lower price | 2 | Manufacturer Product | A credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer | 3 | Account Level | A stand-alone discount that is not applied against any service but instead as a stand-alone product | 4 | Subsidized | A credit for telephone service where the telephone provider provides a service to a lifeline eligible customer. The credit is applied to the subscriber line charge | 5 | Goodwill | A credit applied to customer invoices for the purpose of engendering customer goodwill. For example, compensation for a service outage | |
| Optional Fields | opt | Optional reporting fields useful in reporting. Optional fields do not impact taxation |
| Attribute Property | prop | Attribute/property value for Sales and Use Transaction/Service pairs |
| Quantity | qty | Quantity to be applied to the line item - taxation is equivalent to repeating the item the number of times of the quantity. The field must be a positive integer greater than or equal to 1. Not supported on Tax Inclusive or Prorated transactions |
| General Ledger Reference | glref | General Ledger Reference field for use in reporting |
See Also
Input Objects
Helpful Pages