Avalara Developer Network Developer excise

Excise Certification

Depending on the scope of your integration and your business practice, your test cases will vary. For development partners, many of these are requirements for certification. If you were to give us full functionality demo, here’s what we’d like to see:

Use Case Expected Outcome
View Configuration elements within the Calling Application Administrative user should be able to view/modify the following to provide system ability to point to various levels of systems (Dev, UAT, Prod):
  • User Id to be used for Excise Platform Authentication
  • Password to be used for Excise Platform Authentication (should be stored encrypted and non-viewable)
Validate Required Data in AvaTax Excise Call You should be able to identify the following values:
  • Company Name or Identifier
  • Effective Date for Transaction
  • Transaction Type
  • Title Transfer Code
  • Product Code per Line Item
  • Origin Information (Terminal or City and State)
  • Destination Information (Terminal or City and State)
  • Units (Gross, Net, and Billed)
Validate Transactional Save Functionality SaveTransactionInd field should not be set in integration code. This can be tested by checking the Company Setting Value for Save Transaction Indicator within web interface:
  • Click Maintenance, click Companies, click the company you wish to edit on the left hand side.
  • On the Settings tab, choose the ‘Avatax Excise’ Settings Category
  • Click the Save Transaction setting, click the copy tab
  • On the copy tab, set the value field to either ‘true’ to save transactions or ‘false’ to not save transactions for XML calls.
  • Click insert to apply the setting change.
  • Future changes to this setting must be done directly to the record inserted in this process.
  • Send in a transaction with it set to True and transaction is saved
  • Send again when it is set to False and no transaction is saved
Run a test transaction with multiple line items Build an input transaction object multiple line items. Transmit the multiple line items and verify that multiple line results are returned. This can be done with the API and the web (page) interface.
Sample Use Case: Process a Diesel Fuel transaction to Wisconsin with Destination Title Transfer where the buyer is licensed as a Indian Tribe Confirm the following transaction:
  • After a buyer is set up in the Excise Platform with a WI Indian Tribe License the transaction should be exempt of taxes when sent in with that Buyer

AvaTax Excise API Integration Checklist

To have your integration Certified by Avalara, we have outlined the areas of integration that are necessary to ensure a stable and robust customer experience using AvaTax Excise with your application. To be certified for Avalara AvaTax Excise, all of the items with an R in the Required column listed below are required elements that must be present in your integration.

Certified for Avalara AvaTax Excise

Certification for Avalara AvaTax Excise requires the delivery of all functional requirements shown below:

Avalara AvaTax Excise Administration & Utilities Administration

Here are the basics for login, logout and authentication functions for Avalara AvaTax Excise:

Required Function Comment
R Login Request Authenticates the user against the configured membership provider and verifies they have access to the specified company. If successful, an authentication token is return as a cookie.
R Login Results True/False
R Logout Logs the current user out of the system and clears their authentication cookie.
R Authentication Authentication does not require calling the AuthenticationService.asmx before calling other web services. At the beginning of the call to the web service, the user is authenticated, and if successful, the call is processed normally. The web service will attach a Forms Authentication cookie to the response to improve performance in subsequent calls, but it is not required to use the cookie (the caller can be re-authenticated each time). The client must keep the TCP connection alive in between calls in order to re-use the cookie while configured to use NTLM. Each new TCP connection will require re-authentication.
Customer Record Integration

Here is a table showing the required basic data elements of the customer record integration to AvaTax Excise:

Required Function Comment
R Legal Name The Name of a company that matches to the name field in the companies table.
R Effective Date Effective date of Business Account.
R Id Code Business Account ID Code - i.e., FEIN, Social Security Number, Canadian Business Number or Custom.
R Custom ID Code Unique Id for the Seller and Buyer which must match the custom_id field on the business_entities table in the Avalara AvaTax Excise application client database.
Process Transactions

The Process Transactions method uses an array of Transactions to calculate taxes based on scenarios predefined in the Avalara AvaTax Excise application:

Required Function Comment
R Send required header level data elements:
  • Company
  • Effective Date
  • Transaction Type
  • Title Transfer Code
  • Incoterms
  • Perspective Business Type
  • Company - The Name of a company that matches to the name field in the companies table within the Avalara AvaTax Excise application Control Database.
  • Effective Date - The date of the product movement (e.g., 9/28/2015).
  • Transaction Type – Description of the event of particular event in a supply chain.
  • Title Transfer Code – Indicates where title transfer is taking place.
  • Incoterms – Delivery terms (required for EU content).
  • Perspective Business Type– Buyer or Seller viewpoint (required for EU content).
N Send optional header level data elements:
  • Invoice Number
  • Invoice Date
  • Fuel Use Code
  • Transportation Mode Code
  • Seller
  • Buyer
  • Previous Seller
  • Next Buyer
  • User Data
  • User Transaction ID
  • Source System
  • Order Type
  • Transaction Lines
  • Transaction Exchange Rates
  • Save Transaction Indicator
  • Debug Indicator
  • Calculation Method
  • Total Dyed Units
  • Total Reporting Taxes
  • Reporting Currency
  • Fuel Use Code - A code to describe the fuel use. Currently not used but included for future taxation scenarios. Field can be used in the profile system.
  • Transportation Mode Code – Transportation method used.
  • Seller / Buyer - Unique Id which must match the custom_id field on the business_entities table in the Avalara AvaTax Excise application client database.
  • User Data - String to hold any data you may want to pass into a transaction and potentially receive back untouched. May also be used for customizing calculations based on business rules.
  • User Transaction ID - A unique Id for the transaction as defined by the calling application.
  • Source System - Hard coded string to identify which system is calling the application with this transaction. Useful when more than a single system is using the application or to separate GUI calls from web service calls.
  • Order Type - A code to describe the order type. Currently not used but included for future taxation scenarios.
  • Save Transaction Indicator - Indicates if the transaction should be saved to the database. Not saving can have a significant performance improvement. If this value is not defined in the transaction the Saving of Transactions is controlled by the Company Setting in the GUI.
  • Debug Indicator - Indicates if the transaction should be calculated with debugging enabled.
N Send optional data elements for VAT:
  • Middleman
  • Customs Status
  • Form A Presented Indicator
  • Simplified Procedure Indicator
  • Chain Leg
  • Form A Presented Indicator - Indicates if Form A is presented for VAT.
  • Simplified Procedure Indicator - Indicates if the simplified procedure is used for VAT.
  • Middleman – 3rd party in a triangulation transaction in the EU
  • Chain Leg – Indicates invoice position in a triangulation transaction in the EU
N Send optional Custom data elements:
  • Custom String 1, 2, 3
  • Custom Numeric 1, 2, 3
  • Custom String - String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules.
  • Custom Numeric - Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules.
Process Invoice Line Transactions

The following table describes functions used to process Invoice Line-level transactions in Avalara AvaTax Excise:

Required Function Comment
R Send required data elements:
  • Invoice Line
  • Product Code
  • Product Code - Identifying code of the product being transported in the line item which needs to match either a product code or an alternate product code in the Avalara AvaTax Excise application client database.
  • Invoice Line – Identifies the given transaction line to a pre-defined invoice line by the calling system
N Send optional data elements:
  • Movement Start Date
  • Movement End Date
  • Blend To Product Code
  • Unit Price
  • Net Units
  • Gross Units
  • Billed Units
  • Line Amount
  • Bill of Lading Number
  • Bill of Lading Date
  • User Data
  • Alternative Fuel Content
  • Blend to Alternative Fuel Content
  • Blend To Indicator
  • Currency
  • Unit of Measure
  • Freight Unit Price
  • Freight Type
  • Freight Line Amount
  • Transaction Line Measures
  • Custom String 1, 2, 3
  • Custom Numeric 1, 2, 3
  • Nth Time Sale
  • Alternative Fuel Content - Numeric value that represents the percentage of alternative fuel contained in the product.
  • Blend to Alternative Fuel Content - Numeric Value that represents the percentage of alternative fuel found in the blend to product.
  • Net/Gross/Billed Units – quantities in Net, Gross, or Billed for the given transaction line
  • Blend To Indicator - Indicates if this record refers to a blended product.
  • Nth Time Sale - Integer to identify how many times a product has been sold in the supply chain.
N Send optional data elements for transaction Origin fields:
  • Origin Country Code
  • Origin Jurisdiction
  • Origin County
  • Origin City
  • Origin Postal Code
  • Origin Type
  • Origin
  • Origin Out City Limit Indicator
  • Origin Excise Warehouse
  • Origin Special Jurisdiction Indicator
  • Origin Address 1,2
  • Origin Special Jurisdictions
Send optional data elements for transaction Destination fields:
  • Destination Country Code
  • Destination Jurisdiction
  • Destination County
  • Destination City
  • Destination Postal Code
  • Destination Type
  • Destination
  • Destination Out City Limit Indicator
  • Destination Excise Warehouse
  • Destination Special Jurisdiction Indicator
  • Destination Address 1,2
  • Destination Special Jurisdictions
  • Origin / Destination - A unique id for the location that should match to a custom_id from the locations table in the Avalara AvaTax Excise application client database.
  • Country Code - ISO standard 3 character country code of the location.
  • Jurisdiction - State or region code.
  • City / County - City/County name of the location that must match a GNIS defined City/County name in the local_jurisdictions table of the Avalara AvaTax Excise application Client database; or a cross reference entry in the common_codes.
  • Special Jurisdictions – Indicator if location belongs to a special jurisdiction
N Send optional data elements for transaction Sale fields:
  • Sale Country Code
  • Sale Jurisdiction
  • Sale County
  • Sale City
  • Sale Postal Code
  • Sale Type
  • Sale Location
  • Sale Out City Limit Indicator
  • Sale Excise Warehouse
  • Sale Special Jurisdiction Indicator
  • Sale Address 1,2
  • Sale Special Jurisdictions
Special Jurisdictions – Indicator if location belongs to a special jurisdiction
N Send optional data elements for transaction Counter fields:
  • Counter Country Code
  • Counter Jurisdiction
  • Counter County
  • Counter City
  • Counter Postal Code
  • Counter Type
  • Counter Party
  • Counter Out City Limit Indicator
  • Counter Excise Warehouse
  • Counter Special Jurisdiction Indicator
  • Counter Address 1,2
  • Counter Fiscal Rep. Indicator
  • Special Jurisdictions – Indicator if location belongs to a special jurisdiction
  • Counter Fiscal Rep. Indicator – Y/N field to identify if a Counterparty Fiscal Rep is present in the Counterparty country.
Transaction Line Measure

The following table describes functions used to process transaction line items when using measurement:

Required Function Comment
R Measure Value Numeric Unit of the Quantity indicator type.
R Quantity Indicator Type of Quantity for the Line referencing Billed, Net or Gross Value. Field is requirement when completing a Transaction Line Measure record.
R Unit of Measure Defines the Unit of Measure for the Transaction Line Measure definition. Field is requirement when completing a Transaction Line Measure record.
Transaction Exchange Rate

Here are the data elements used to process transaction line items when using exchange rates:

Required Function Comment
R Effective Date Date the Conversion Factor is valid for transaction.
R Conversion Factor Numeric Amount determining the conversion factor between the from and to currencies.
R From Currency Currency type Value must start with for transaction. Field is required when completing an exchange record.
R To Currency Currency type Value will end up as in transaction. Field is required when completing an exchange record.
Transaction Line Special Jurisdiction

The following data elements are required for transactions using special jurisdiction codes and types:

Required Function Comment
R Special Jurisdiction Code Indicate the name of the special jurisdiction.
R Special Jurisdiction Type Indicates taxation level of the special jurisdiction.
Transaction Results

These functions are used to determine transaction results:

Required Function Comment
R Transaction ID Unique Id assigned to the Transaction by the Avalara AvaTax Excise application.
R Return Code A numeric representation of the success or failure of the transaction.
R Total Tax Amount Sum of all taxes on all line items and on the invoice itself.
N User Transaction ID A unique Id for the transaction as defined by the calling application which was passed in by the calling application.
N Status String defining the status of the transaction in the AvaTax Excise system.
N Transaction Taxes Object defining the individual taxes returned from the transaction.
N Transaction Errors Object defining the individual errors returned from the transaction.
N User Return Value String that returns the User Data Field.
Transaction Tax Functions

This table describes specific functions used to process tax transactions with Avalara AvaTax Excise:

Required Function Comment
R Sequence Id Avalara AvaTax Excise application calculated value that uniquely identifies the tax item within the transaction results.
R Product Category Numeric representation of the type of product being taxed defined in the product_categories table in the Avalara AvaTax Excise application.
N Send optional data elements:
  • Transaction Line
  • Invoice Line
  • Country Code
  • Jurisdiction
  • Local Jurisdiction
  • Tax Type
  • Rate Type
  • Rate Subtype
  • Calculation Type Indicator
  • Tax Rate
  • Tax Quantity
  • Tax Amount
  • Tax Exempt Indicator
  • Deferred Indicator
  • Payable To Code
  • Sales Tax Base Amount
  • License Number
  • User Returned Value
  • Scenario Id
  • Scenario Tax Group Id
  • Scenario Sequence
  • Rate Description
  • Currency
  • Unit of Measure
  • Subtotal Indicator
  • Transaction Tax Amounts
  • Status Code
  • Quantity Indicator
  • Reporting Tax Amount
  • Reporting Tax Currency
  • License Number - The tax jurisdiction license number that applies to this transaction.
  • User Returned Value - String to hold any data you may want to pass into a transaction and potentially receive back untouched. May also be used for customizing calculations based on business rules.
  • Scenario Id and Scenario Tax Group Id - Definition that was applied to these tax items.
  • Subtotal Indicator - Indication of which field(s) to use for the sales tax base of the tax (Freight Only, Unit Price Only, Combined).
  • Status Code - The calculation status of the tax.