Avalara Developer Network Developer excise

Excise API

The Avalara AvaTax Excise Web Service is a SOAP web service that is the external programmatic interface into the Avalara AvaTax Excise application. It provides for a platform independent mechanism to obtain tax calculation information. This document defines the object structure, and an introduction on how to consume the web service for use in customer programs. At this time, Excise sample code/libraries are available in .NET only. Versioning: The Excise Tax SOAP API currently implements inline explicit versioning. The method name contains the version number. This document describes version 5_18_0, which is NOT is the current version of the service. Please replace this when using newer or older versions of the service. Please note the application name changes effective 7/31/2014:

  • Avalara Returns Excise replaces Zytax Compliance
  • Avalara AvaTax Excise replaces Zytax Determination
  • Avalara Government replaces Zytax Government

URLs

  • Development Authentication Service: https://psd.avalara.net/authenticationservice.asmx?wsdl
  • Development Tax Determination: https://psd.avalara.net/determination/taxdetermination.asmx?wsdl
  • User Acceptance Authentication Service: https://exciseua.avalara.net/authenticationservice.asmx?wsdl
  • User Acceptance Tax Determination: https://exciseua.avalara.net/determination/taxdetermination.asmx?wsdl
  • Production Authentication Service: https://excise.avalara.net/authenticationservice.asmx?wsdl
  • Production Tax Determination: https://excise.avalara.net/determination/taxdetermination.asmx?wsdl

Authentication

The Excise Platform Authentication Web Service is a SOAP/XML web service that is the external programmatic interface for authentication against the Excise Platform. It provides for a platform independent mechanism to obtain an authorization token which can be used when calling other web services. This document defines the object structure, and an introduction on how to consume the web service for use in customer programs. Web service authentication in the Excise platform has 3 basic forms:

  • Anonymous: no authentication required to call a web service
  • Forms: Forms authentication requires calling the AuthenticationService.asmx before calling other web services. This function returns an ASP.Net Forms authentication cookie with the response which needs to be passed along with each future web service call. Users wishing to use Forms authentication should see the Login and Logout methods documented below.
  • NTLM: NTLM 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.

Login

For use with Forms Authentication. Forms authentication requires calling the AuthenticationService.asmx before calling other web services. This function returns an ASP.Net Forms authentication cookie with the response which needs to be passed along with each future web service call. 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.

Api Endpoint
POST https://excise.avalara.net/authenticationservice.asmx?login

Headers
Content-Type: application/xmlSOAPAction: http://taxes.services.fuelquest.com/Login

Post Body Parameters

xmlns:xsi
string
xmlns:xsd
string
Body
Login
userName
string
password
string
companyName
string

Response

xmlns:xsi
string
xmlns:xsd
string
Body
LoginResponse
LoginResult
boolean

Logout

For use with Forms Authentication. Logs the current user out of the system and clears their authentication cookie.

Api Endpoint
POST https://excise.avalara.net/authenticationservice.asmx?logout

Headers
Content-Type: application/xmlSOAPAction: http://taxes.services.fuelquest.com/Logout

Post Body Parameters

xmlns:xsi
string
xmlns:xsd
string
Body
Logout
string

Response

xmlns:xsi
string
xmlns:xsd
string
Body
LogoutResponse
string

Process Transactions

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

Api Endpoint
POST https://excise.avalara.net/taxdetermination.asmx?processTransactions

Headers
Content-Type: application/xmlSOAPAction: http://taxes.services.fuelquest.com/ProcessTransactions

Post Body Parameters

xmlns:xsi
string
xmlns:xsd
string
Body
ProcessTransactions_5_18_0
Array[Transactions]
Company
Required

The Name of a company that matches to the name field in the companies table within the Avalara AvaTax Excise application Control Database (eg. Determination Sample)

string
EffectiveDate
Required

The date of the physical product movement (eg. 3/27/2009)

string
InvoiceNumber

An identifying number of the invoice to be taxed (eg. INV1011)

string
InvoiceDate

The date of the invoice to be taxed (eg. 3/27/2009)

string
FuelUseCode

A code to describe the fuel use. Currently not used but included for future taxation scenarios

string
TransactionType
Required

Type of transactions on this invoice (eg, Above, Below, Rack)

string
TransportationModeCode

Type of transportation mode used to transport fuel between locations (eg, J, PL, R)

string
TitleTransferCode
Required

Definition of where the title transfer takes place (eg, ORIG, DEST)

string
Seller

Unique ID for the seller which must match the custom_id field on the business_entities table in the Avalara AvaTax Excise application client database (eg, Sel321, 7, sel345)

string
Buyer

Unique ID for the buyer which must match the custom_id on the business_ entities table in the Avalara AvaTax Excise application client database (eg, Buy784, 24324, buy97887)

string
PreviousSeller

ID of the Previous Seller (eg, Sel321, 7, sel345)

string
NextBuyer

ID of the Next Buyer (eg, Buy784, 24324, buy97887)

string
SellerVATNumber

Seller VAT Registration Number (eg, 1234567890123456790)

string
BuyerVATNumber

Buyer VAT Registration Number (eg, 1234567890123456790)

string
CustomStatus

Indicates the Customs status for VAT (eg, EUY,EUN)

string
FormAPresentedInd

Indicates if Form A is Presented for VAT (eg, Y,N)

string
SimplifiedProcedureInd

Indicates if the simplified procedure is used for VAT (eg, Y,N)

string
Incoterms

International Chamber of Commerce (ICC) rules for the use of domestic and international trade terms (eg, EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAF, DES, DEQ, DDU, DDP)

string
UserData

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

string
UserTranId

A unique Id for the transaction as defined by the calling application (eg, 678, 23823982, 32324)

string
SourceSystem

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 (eg, SAAS, iLynx, etc)

string
CustomString1

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, TEST, Purple, 111)

string
CustomString2

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, TEST, Purple, 111)

string
CustomString3

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, TEST, Purple, 111)

string
CustomNumeric1

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, 100, 0.0125, 500000000)

number
CustomNumeric2

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, 100, 0.0125, 500000000)

number
CustomNumeric3

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. (eg, 100, 0.0125, 500000000)

number
OrderType

A code to describe the order type. Currently not used but included for future taxation scenarios.

string
SaveTransactionInd

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. (eg, Y,N, )

string
DebugInd

Indicates if the transaction should be calculated with debugging enabled. (eg, Y,N)

string
CalculationMethod

Indicates which company specific configuration should be used when calculating the transaction. (eg, NORMAL, WITHOUT_COMPANY, PROFILES_ONLY, LICENSES_ONLY)

string
TotalDyedUnits

The total amount of dyed product purchased by the customer for the month of the transaction. (eg, 100, 345.3, 4005)

number
TotalReportingTaxes

Sum of all resulting taxes from the reporting_tax_amount field (eg, 2.00, 0.82)

number
ReportingCurrency

Currency the taxes need to be reported in which may differ from the currency of tax rate (eg, USD, GBP, EUR)

string
Array[TransactionLines]
InvoiceLine
Required

A unique identifier within the transaction for the invoice line item (eg, 1, 2, 3)

number
MovementStartDate

The date that the product on the line item begins to be transported from the origin (eg, 3/27/2009)

string
MovementEndDate

The date that the product on the line item reaches its destination (eg, 3/27/2009)

string
ProductCode
Required

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 (eg, 065, E00, 241)

string
BlendToProductCode

If used in blending the product code of the final product which needs to match a product code or an alternate product code in the Avalara AvaTax Excise application client database (eg, B10, E10)

string
UnitPrice

The price per unit of the product (eg, 1.37, 2.29, 44.34)

number
NetUnits

The net units of product (eg, 100, 345.3, 4005)

number
GrossUnits

The gross units of product (eg, 100, 345.3, 4005)

number
BilledUnits

The billed units of product (eg, 100, 345.3, 4005)

number
LineAmount

The total amount of value of product on the line item calculated by BilledUnits * UnitPrice, If left blank the Avalara AvaTax Excise application calculate (eg, 137.00, 456.58, 5213.47)

number
BillOfLadingNumber,

Bill of lading or Manifest number of the load (eg, Bol4585, 100458)

string
BillOfLadingDate

Bill of lading or Manifest Date of the load (eg, 3/27/2009)

string
OriginCountryCode

ISO standard 3 character country code of the origin location (eg, USA, CAN)

string
OriginJurisdiction

State or Region code of the originating location of the load (eg, WI, TX, ID)

string
OriginCounty

County name of the origin location that must match a GNIS defined County name in the local_jurisdictions table of the Avalara AvaTax Excise application Client database; or a cross reference entry in the common_codes (eg, Brown, Ada, Marathon)

string
OriginCity

City name of the origin location that must match a GNIS defined City name in the local_jurisdictions table of the Avalara AvaTax Excise application client database; or a cross reference entry in the common_codes (eg, Boise, Houston, Milwaukee)

string
OriginPostalCode

Postal Code of the origin location that is available here for information purposes only. Not used in calculation of taxes at this time. 54126, 70012, 80013

string
OriginType

Type of facility that the product originates from PIPELINE, REFINERY, TERMINAL, TRUCK

string
Origin

A unique id for the origin location that should match to a custom_id from the locations table in the Avalara AvaTax Excise application client database Loc4528

string
OriginOutCityLimitInd

Single character that specifies if the origin location resides within or outside of the city limits Y, N

string
OriginExciseWarehouse

Excise Warehouse Number of the Origin Free-form

string
OriginSpecialJurisdictionInd

Indicates if the origin has special jurisdictions. Y, N

string
OriginSpecialJurisdictions

Array of special jurisdictions for the origin. N/A

string
DestinationCountryCode

ISO standard 3 character country code of the destination location USA, CAN

string
DestinationJurisdiction

State or Region code of the destination location of the load WI, TX, ID

string
DestinationCounty

County name of the destination location that must match a GNIS defined County name in the local_jurisdictions table of the Avalara AvaTax Excise application Client database; or a cross reference entry in the common_codes Brown, Ada, Marathon

string
DestinationCity

City name of the destination location that must match a GNIS defined City name in the local_jurisdictions table of the Avalara AvaTax Excise application client database; or a cross reference entry in the common_codes Boise, Houston, Milwaukee

string
DestinationPostalCode

Postal Code of the destination location that is available here for information purposes only. Not used in calculation of taxes at this time. 54126, 70012, 80013

string
DestinationType

Type of receiving facility for the product PIPELINE, REFINERY, TERMINAL, TRUCK

string
Destination

A unique id for the destination location that should match to a custom_id from the locations table in the Avalara AvaTax Excise application client database Loc4528

string
DestinationOutCityLimitInd

Single character that specifies if the destination location resides within or outside of the city limits Y, N

string
DestinationSpecialJurisdicitonInd

Indicates if the destination has special jurisdictions. Y, N

string
Array[DestinationSpecialJurisdictions]
SpecialJurisdictionCode
Required

The unique code of the special jurisdiction.

string
SpecialJurisdictionType
Required

The local jurisdiction type of the special jurisdiction.

string
DestinationExciseWarehouse

Excise Warehouse Number of the Destination Free-form

string
SaleCountryCode

ISO standard 3 character country code of the Sale location USA, CAN

string
SaleJurisdiction

State or Region code of the Sale location of the load WI, TX, ID

string
SaleCounty

County name of the Sale location that must match a GNIS defined County name in the local_jurisdictions table of the Avalara AvaTax Excise application Client database; or a cross reference entry in the common_codes Brown, Ada, Marathon

string
SaleCity

City name of the Sale location that must match a GNIS defined City name in the local_jurisdictions table of the Avalara AvaTax Excise application client database; or a cross reference entry in the common_codes Boise, Houston, Milwaukee

string
SalePostalCode

Postal Code of the Sale location that is available here for information purposes only. Not used in calculation of taxes at this time. 54126, 70012, 80013

string
SaleType

Type of receiving facility for the product PIPELINE, REFINERY, TERMINAL, TRUCK

string
SaleLocation

A unique id for the Sale location that should match to a custom_id from the locations table in the Avalara AvaTax Excise application client database Loc4528

string
SaleOutCityLimitInd

Single character that specifies if the Sale location resides within or outside of the city limits Y, N

string
SaleExciseWarehouse

Excise Warehouse Number of the Sale Location Free-form

string
SaleSpecialJurisdictionInd

Indicates if the sale locaiton has special jurisdictions. Y, N

string
Array[SaleSpecialJurisdictions]
SpecialJurisdictionCode
Required

The unique code of the special jurisdiction.

string
SpecialJurisdictionType
Required

The local jurisdiction type of the special jurisdiction.

string
CounterCountryCode

ISO standard 3 character country code of the Counter location USA, CAN

string
CounterJurisdiction

State or Region code of the Counter location of the load WI, TX, ID

string
CounterCounty

County name of the Counter location that must match a GNIS defined County name in the local_jurisdictions table of the Avalara AvaTax Excise application Client database; or a cross reference entry in the common_codes Brown, Ada, Marathon

string
CounterCity

City name of the Counter location that must match a GNIS defined City name in the local_jurisdictions table of the Avalara AvaTax Excise application client database; or a cross reference entry in the common_codes Boise, Houston, Milwaukee

string
CounterPostalCode

Postal Code of the Counter location that is available here for information purposes only. Not used in calculation of taxes at this time. 54126, 70012, 80013

string
CounterType

Type of receiving facility for the product PIPELINE, REFINERY, TERMINAL, TRUCK

string
CounterParty

A unique id for the Counter location that should match to a custom_id from the locations table in the Avalara AvaTax Excise application client database Loc4528

string
CounterOutCityLimitInd

Single character that specifies if the Counter location resides within or outside of the city limits Y, N

string
CounterSpecialJurisdicitonInd

Indicates if the Counter has special jurisdictions. Y, N

string
CounterExciseWarehouse

Excise Warehouse Number of the Counter Free-form

string
CounterFiscalRepInd

Indicates if the Counter is a fiscal rep. Y, N

string
UserData

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

string
AlternativeFuelContent

Numeric value that represents the percentage of alternative fuel contained in the product 0.10, 0.85

number
BlendToAltFuelContent

Numeric Value that represents the percentage of alternative fuel found in the blend to product 0.10, 0.85

number
BlendToInd

Indicates if this record refers to a blended product Y, N

string
Currency

Type of Currency the line item Unit Price and Line Amount are defined in USD, EUR, GBP

string
UnitofMeasure

The Unit of Measure the line item Net, Gross, and Billed units are defined in BRL, GAL, LTR

string
FreightUnitPrice

The price per unit of the freight 1.37, 2.29, 44.34

number
FreightType

The type of freight. NONE, ITEMIZED_COMMON_CARRIER, NONITEMIZED_NOT_COMMON_CARRIER

string
FreightLineAmount

The total amount of value of product on the line item calculated by BilledUnits * FreightUnitPrice, If left blank the Avalara AvaTax Excise application will calculate 137.00, 456.58, 5213.47

number
Array[TransactionLineMeasures]
QuantityInd

Type of Quantity for the Line referencing Billed, Net or Gross Value B, N, G

string
UnitOfMeasure

The Measurement type the Measure Value is defined in BRL, GAL, LTR

string
MeasureValue
Required

Numeric Unit of the Quanity indicator type 100, 200, 300

number
CustomString1

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. TEST, Purple, 111

string
CustomString2

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. TEST, Purple, 111

string
CustomString3

String to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. TEST, Purple, 111

string
CustomNumeric1

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. 100, 0.0125, 500000000

number
CustomNumeric2

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. 100, 0.0125, 500000000

number
CustomNumeric3

Decimal to hold data you want to pass into a transaction to be used for customizing calculations based on business rules. 100, 0.0125, 500000000

number
NthTimeSale

Decimal to tell how many times a product has been sold in the supply chain. 1,2,3

number
Array[TransactionExchangeRates]
FromCurrency

Currency type Value must start with USD, EUR, GBP

string
ToCurrency

Currency type Value will end up as USD, EUR, GBP

string
EffectiveDate
Required

Date the Conversion Factor is valid for 4/23/2009, 5/17/2009

string
ConversionFactor
Required

Numeric Amount determining the conversion factor between the from and to currencies 0.123234, 4.3245

number

Response

xmlns:xsi
string
xmlns:xsd
string
Body
ProcessTransactions_5_18_0Response
ProcessTransactions_5_18_0Result
TransactionResultSummary_5_18_0
NumberProcessed

Number of transactions processed during the call to ProcessTransactions_5_18_0

number
NumberSuccess

Number of transactions processed that did not contain errors and returned a valid result

number
NumberFailed

Number of transactions processed that did contain errors

number
Array[TransactionResults]
UserTranId

A unique Id for the transaction as defined by the calling application which was passed in by the calling application in the Transaction_5_18_0 object

string
TranId
Required

Unique Id assigned to the Transaction by the Avalara AvaTax Excise application

number
Status

String defining the status of the transaction in the Tax Determination System

string
ReturnCode
Required

A numeric representation of the success or failure of the transaction

number
TotalTaxAmount
Required

Sum of all taxes on all line items and on the invoice itself

number
Array[TransactionTaxes]
SequenceId
Required

Avalara AvaTax Excise application calculated value that uniquely identifies the tax item within the transaction results 1, 2, 3

number
TransactionLine

The Transaction Line number passed in from the customer in the TransactionLine_2_0 object 1, 2, 3

number
InvoiceLine

The numeric invoice line passed in the calling application 1, 2, 3

number
CountryCode

3 Character ISO country code USA, CAN

string
Jurisdiction

2 Character code for the taxing jurisdiction ID, US, TX

string
LocalJurisdiction

GNIS standard name for a local jurisdiction such as a city or county. If a tax is not a result of a local jurisdiction it’s set to NONE Boise, NONE, Ada

string
ProductCategory
Required

Numeric representation of the type of fuel being taxed defined in the product_categories table in the Avalara AvaTax Excise application 1, 4, 22

number
TaxingLevel

Government level of taxation for the current tax item from the rates table in the Avalara AvaTax Excise application FEDERAL, STATE, LOCAL

string
TaxType

Type of tax for the current tax item from the rates table in the Avalara AvaTax Excise application FUEL, SALESUSE

string
RateType

Type of rate for the current tax item from the rates table in the Avalara AvaTax Excise application TAX, FEE

string
RateSubtype

Further definition of the rate for the current tax item from the rates table in the Avalara AvaTax Excise application NONE, REFUND, HIGH

string
CalculationTypeInd

Type of calculation for the rate as defined in the rates table in the Avalara AvaTax Excise application C (currency per unit), P (percentage), F (fixed)

string
TaxRate

The tax rate for the current tax item .025, .05

number
TaxQuantity

Number of units of product being taxed in this tax item 100, 4000, 3214

number
TaxAmount

Calculated tax amount for the tax line 2.50, 50.00

number
TaxExemptionInd

Indication of whether a tax is exempt or not Y, N

string
DeferredInd

Indication of whether a tax is deferred or not Y, N

string
PayableToCode

(eg, R,S)

string
SalesTaxBaseAmount

Amount of Sales tax for the current tax item 234.00, 554.00

number
LicenseNumber

The tax jurisdiction license number that applies for this transaction. 200984235, 894234567

string
UserReturnedValue

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

string
ScenarioId

A definition of the scenario that was applied in this tax item 100123, 119123

number
ScenarioTaxGroupId

A definition of the scenario tax group that was applied in this tax item 8245,321

number
ScenarioSequence

Sequence Id of the scenario_taxes table record used for this tax item 1, 2, 3, 4

number
RateDescription

A short text description (pulled from the comments field of the rate table) of the rate that is being applied with this tax item Texas Delivery Fee

string
Currency

Type of Currency the line item Unit Price and Tax Amount are defined in USD, EUR, GBP

string
UnitofMeasure

The Unit of Measure the tax quantity isdefined in BRL, GAL, LTR

string
SubtotalInd

Indication of which field(s) to use for the sales tax base of the tax. (Freight Only, Unit Price Only, Combined). C, F, U

string
Array[TransactionTaxAmounts]
SequenceId
Required

Ordinal id for the Tax Amount

number
Currency

Currency type of the tax amount

string
TaxAmount
Required

Amount of tax in the defined currency

number
StatusCode

The calculation status of the tax. ACTIVE, INACTIVE, EXCLUDED

string
QuantityInd

Type of Quantity used to calculate the tax referencing Billed, Net or Gross Value B, N, G

string
ReportingTaxAmount

Tax Amount Converted to the Reporting Currency specified on the header 0.82, 2.90

number
ReportingTaxCurrency

Currency requested in the reporting currency field on the header USD, EUR, GBP

string
Array[TrasactionErrors]
SequenceId
Required

Ordinal id for the error 1, 2, 3

number
ErrorCode

Numeric code representing an error in the Avalara AvaTax Excise application. -890, -892

string
ErrorMessage

String description of the error Rate for CountryCode: USA,Jurisdiction: ID,LocalJurisdiction: NONE,EffectiveDate: 3/27/2009 12:00:00 AM TaxingLevel: STATE TaxType: SALESUSE RateType: TAX,RateSubtype: NONE,ProductCategory: 0 was not found.

string
ErrorLevelInd

Text describing the severity of the error. C - Critical, W - Warning

string
UserReturnValue

String that returns the UserData field passed into the Transactions_5_18_0 object

string