Chapter 4.3.11 - Transaction Information

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