Avalara Developer Network Developer communications

Chapter 4.3.11 - Transaction Information

Communications REST v2 takes the transaction as a whole and bases the returned taxes off of the information provided.

Each transaction contains the following information:

A product (defined by the transaction/service pair) can return different taxes, or no taxes, depending on the selections made. For example, setting the following 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 in order to get the proper taxes back.

Company (Seller) Data

Company data defines the company or seller. Set these keys in the CompanyData object. See CompanyData Reference for more information.

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 the Invoice, Location, or LineItem objects.
See Invoice, Location, and LineItem for more information.

Name Key Description
Customer Type cust Specifies the type of customer involved in the transaction. Customer Type is set on the invoice but can be overridden on the 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. Lifeline is 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 in terms of where the transaction takes place, what is being be taxed, and other details. Set these keys in the Invoice or LineItem objects.

Transactions can also be customized through Tax Overrides and Safe Harbor Overrides.

Invoice Keys

See Invoice Reference for more information.

Name Key Description
DocumentCode 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 DocumentCode 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
Bill To 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 to be applied to the transaction or invoice. Normally set to the bill date, invoice date, or call date (as applicable). Invoice Date is 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

LineItem Keys

See LineItem Reference for more information.

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. Defaults to 0 if not set
When local service is provided, a transaction should be generated with Lines 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 and local telecommunications relay service taxes and other assorted taxes.
Locations loc Specifies the number of customer locations
Defaults to 0 if not set
Minutes min Specifies the length of a phone call. Defaults to 0 if not set
Used in the generation of taxes that are specified as per minute flat fees in some taxing jurisdictions. The number is a double so any seconds added should be in decimal format. For example, use 20.5 for 20 minutes and 30 seconds.
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
Bridge Conferencing brdg Data for conference bridge transactions
Transaction Type tran Transaction Type ID of the service being taxed. Use the /api/v2/afc/tspairs 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 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