Avalara Developer Network Developer communications

Chapter 4.3.11 - Transaction Information

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

Each transaction contains the following information:

  • Company (Seller) Data
  • Customer (Buyer) Data
  • Transaction (Invoice and Line Item) Data

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), Sales Tax at the State and County tax levels is returned. Because of this, it is imperative that the transaction information is set correctly in order to get the proper taxes back.

Company Data

Company data defines the company or seller. Set these keys in the CompanyData object. More information about CompanyData can be found here.

Name Key Description
Business Class bscl Specifies whether the business making the transaction is an Incumbent Local Exchange Company (ILEC) or not an ILEC
  • Not an ILEC (default): Engaged in selling services competing with an incumbent provider
  • ILEC: Engaged in selling services over company-owned lines and equipment
  • Use Not an ILEC if neither class applies

Only impacts Communications transactions in certain jurisdictions, such as Oregon
Service Class svcl Delineates the primary activity of an organization as Local Service or Long Distance
  • Primary Local (default): Carriers vending their services with over 50% of the gross business activities in Local Service revenue
  • Primary Long Distance: Carriers vending their services with over 50% of the gross business activities in Long Distance revenue

Only impacts Communications transactions in certain jurisdictions, such as New York
Facilities fclt Specifies whether the transaction is sold over tangible facilities controlled by the seller
  • True (default): Seller delivering the service owns or controls the facilities used to provide the service (facilities based)
  • False: Carrier does not own the facilities (non-facilities based)

In some jurisdictions, tax outcomes will vary depending on whether the service is delivered over infrastructure controlled by the seller
Franchise frch Indicates that the seller provides services sold pursuant to a franchise agreement between the carrier and the jurisdiction
  • True (default): Seller has a franchise agreement with the jurisdiction
  • False: 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
  • False (default): Company is not rate-regulated
  • True: Company is rate-regulated

Unless the seller is registered with the state regulatory commission as a rate-regulated, incumbent provider, all transactions should be set to false
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 Data

Customer data defines the customer or buyer. Set these keys in the Invoice or Location objects.
More information about Invoice can be found here. More information about Location can be found here.

Name Key Description
Customer Type cust Specifies the type of customer involved in the transaction
  • Residential: Transactions made by the customer for home use
  • Business: Transactions made at a place of business
  • 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
  • Industrial: Transactions made at an industrial business
Lifeline lfln Indicates if the customer is a Lifeline participant
  • False (default): Collects all taxes
  • True: Turns off the calculation of taxes that are not collected from Lifeline recipients
Incorporated int Specifies whether the customer is involved in this transaction inside or outside of the Local level of the jurisdiction.
  • True (default): Jurisdiction is inside an incorporated location
  • False: Jurisdiction is outside an incorporated location. This option usually results in no local taxes returned

If unsure, set this key to true
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 of the transaction. Set these keys in the Invoice or LineItem objects.

In addition to these objects, transactions can also be customized through Tax Overrides and Safe Harbor Overrides.

Invoice Keys

More information about Invoice can be found here.

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
DocumentCode must be set if Commit is true
Commit cmmt Specifies if the DocumentCode should be committed as soon as the tax calculation is processed
  • False (default): DocumentCode is not committed or is uncommitted if previously committed and still within the current reporting period
  • True: DocumentCode is committed
  • If DocumentCode is provided but Commit is null, Commit is defaulted to false
  • If Commit is true, DocumentCode must be set
Bill To Jurisdiction bill Identifies the location to be billed
Transaction 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 Mode invm Indicates if all line items within an invoice should be processed individually or as one invoice
  • True (default): line items are part of a single invoice
  • False: line items are unrelated
Return Detail dtl Indicates if individual line item taxes should be included in response
  • True (default): return line item level tax results
  • False: do not return line item level tax results
  • If true, Return Summary must be set to false
Return Summary summ Indicates if the summarized taxes for the invoice should be included in the response
  • False (default): do not return summarized tax results
  • True: return summarized tax results
  • If true, Return Detail must be set to false
Optional Fields opt Optional reporting fields useful in reporting. Optional fields do not impact taxation

LineItem Keys

More information about LineItem can be found here.

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 invoice's BillTo location is used
Termination/Ship To Jurisdiction to Location for the destination point. If null, the invoice's 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
  • wholesale: specifies that the transaction is a sale to another company that will resell the product or service to a consumer
  • Retail: specifies that the transaction is a sale to an end user
  • Consumed: Sales and Use only. Specifies that the transaction is for an item that is consumed directly
  • 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
  • False (default): taxes not included in the Line Item charge
  • True: taxes are 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. See AFC Telecom Mapping Guidelines for a list of transaction type IDs.
Service Type serv Service Type ID of the service being taxed. See AFC Telecom Mapping Guidelines for a list of service type IDs.
Debit dbt Indicates if the transaction is prepaid
  • False (default): Debit does not apply
  • True: perform a debit call tax calculation

Only set Debit to true if you are a prepaid seller
Adjustment adj Indicates if this line item is a credit or adjustment
  • False (default): not a credit or adjustment
  • True: is a credit/adjustment
Adjustment Method adjm Specifies how an adjustment should be processed
  • Default (default): adjustment is processed exactly like a similar charge transaction but with a negative tax result. Standard tax brackets are applied
  • Least Favorable Rate: tax brackets are applied to produce the smallest tax refund. This is only useful for taxes with multiple tiers or brackets
  • Most Favorable Rate: tax brackets are applied to produce the largest tax refund. This is only useful for taxes with multiple tiers or brackets

If unsure, use Default
Discount Type disc Identifies the discount type for an adjustment
  • None (default): discount type not applicable
  • Retail Product: an amount subtracted from the original price to arrive at a lower price
  • Manufacturer Product: a credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer.
  • Account Level: a stand-alone discount that is not applied against any service but instead as a stand-alone product
  • 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
  • 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