Avalara Developer Network Developer avaTax

AvaTax REST API

The AvaTax REST API exposes the most commonly used available for interacting with the AvaTax service, allowing calculation of tax, modification of documents, and validation of addresses. If you're unsure of which API to use, a full comparison of the differences between the functionality provided by our REST and SOAP interfaces is documented here. The SOAP API reference is also available.

Have development credentials? Generate a Postman Collection with your account info!


Calculate Tax and Record a Document

Calculates taxes on a document such as a sales order, sales invoice, purchase order, purchase invoice, or credit memo. To use an XML request/response, use the URL /1.0/tax/get.xml

Api Endpoint
POST https://development.avalara.net/1.0/tax/get

Headers
Authorization: Basic aHR0cHdhdGNoOmY=Content-Type: text/json,text/xml

Post Body Parameters

BusinessIdentificationNo

The buyer’s VAT ID. Using this value will force VAT rules to be considered for the transaction. This may be set on the document or the line. Note that this should be a valid VAT number, and this field should not be used for any other purpose.

string
Commit

Default is false. Setting this value to true will put the document in a Committed status, preventing further document status changes, except voiding with CancelTax.

boolean
Client

An identifier of software client generating the API call.

string
CompanyCode

The case-sensitive code that identifies the company in the AvaTax account in which the document should be posted. This code is declared during the company setup in the AvaTax Admin Console. If no value is passed, the document will be assigned to the default company. If a value is passed that does not match any company on on the account, an error is returned.

string
CustomerCode
Required

The case-sensitive client application customer reference code. This is required since it is the key to the Exemption Certificate Management Service in the Admin Console.

string
CurrencyCode

3 character ISO 4217 compliant currency code. If unspecified, a default of USD will be used.

string
CustomerUsageType

The client application customer or usage type. More information about this value is available in the Avalara Help Center.

string
DetailLevel

Specifies the level of detail to return. Summary - summarizes document and jurisdiction detail with no line breakout Document - only document detail Line - document and line detail Tax - document, line and jurisdiction detail

string
Discount

The discount amount to apply to the document. This may be used along with the line attribute Discounted in order to distribute a set discount amount proportionally across the applicable document lines. This should be an amount, not a percent.

number
DocCode

While this is an optional field, serious consideration should be given to using it. If no value is sent, AvaTax assigns a GUID value to keep the document unique. This can make reconciliation a challenge.

string
DocType

The document type specifies the category of the document and affects how the document is treated after a tax calculation. If no DocType is specified in the request, SalesOrder will be used. SalesOrder: This is a temporary document type and is not saved in tax history. GetTaxResult will return with a DocStatus of Temporary. SalesInvoice: The document is a permanent invoice; document and tax calculation results are saved in the tax history. GetTaxResult will return with a DocStatus of Saved. PurchaseOrder: This is a temporary document type and is not saved in tax history. GetTaxResult will return with a DocStatus of Temporary. PurchaseInvoice : The document is a permanent invoice; document and tax calculation results are saved in the tax history. GetTaxResult will return with a DocStatus of Saved. ReturnOrder: This is a temporary document type and is not saved in tax history. GetTaxResult will return with a DocStatus of Temporary. ReturnInvoice: The document is a permanent sales return invoice; document and tax calculation results are saved in the tax history GetTaxResult will return with a DocStatus of Saved.

string
DocDate

The date on the invoice, purchase order, etc. Format YYYY-MM-DD. If omitted, this will default to the current date.

string
ExemptionNo

Any string value will cause the sale to be exempt. This should only be used if your finance team is manually verifying and tracking exemption certificates.

string
LocationCode

Also referred to as a Store Location, Outlet Id, or Outlet code. Location code is a value assigned by some state jurisdictions that identifies a particular store location. These states may require tax liabilities to be broken out separately for each store location.

string
PosLaneCode

Permits a point of sale application to record the unique code / ID / number associated with the terminal processing a sale.

string
PurchaseOrderNo

Your customer’s purchase order number.

string
ReferenceCode

Additional information used for reporting. For returns, this can refer to the DocCode of the original invoice.

string
TaxOverride
Reason
Required

This provides the reason for a tax override for audit purposes. Typical reasons include: 'Return', 'Layaway', 'Imported'.

string
TaxOverrideType
Required

Must be one of the following: None: Default TaxAmount: The TaxAmount overrides the total tax for the document. This is used for imported documents, returns, and layaways where the tax has already been calculated either by AvaTax or another means. Exemption: Exemption certificates are overridden making the document taxable. This may be used for situations where a normally exempt entity needs to be treated as not exempt. TaxDate: The TaxDate overrides the DocDate as the effective date used for tax calculation. This may effect rates, rules and other factors.

string
TaxDate

Must be valid date, required if TaxOverrideType is TaxDate, the override tax date to use. This is used when the tax has been previously calculated as in the case of a layaway, return or other reason indicated by the Reason element. If the date is not overridden, then it should be set to the same as the DocDate.

string
TaxAmount

Must be numeric, required if TaxOverrideType is TaxAmount. The overriding amount of tax to apply. If at the document level, this is distributed across all taxable rows.

string
Array[Addresses]
AddressCode
Required

Reference code uniquely identifying this address instance.

string
Line1
Required

Address line 1, recommended if latitude and longitude are not provided.

string
Line2

Address line 2

string
Line3

Address line 3

string
City
Required

City name, required unless PostalCode is specified and/or latitude and longitude are provided.

string
Region
Required

State, province, or region name. Required unless Ccity is specified and/or latitude and longitude are provided.

string
Country

Two-character ISO country code. If not provided, will default to 'US'.

string
PostalCode
Required

Postal or ZIP code, Required unless city and region are specified, and/or latitude and longitude are provided.

string
Latitude

Geographic latitude. If Latitude is defined, it is expected that the longitude field will also be provided. Failure to do so will result in operation error. Calculation by latitude/longitude is available for the United States only. If a latitude/longitude value outside of the US is provided, the service will return an error.

number
Longitude

Geographic longitude. If Longitude is defined, it is expected that the latitude field will also be provided. Fail to do so will result in operation error. Calculation by latitude/longitude is available for the United States only. If a latitude/longitude value outside of the US is provided, the service will return an error.

number
TaxRegionId

AvaTax tax region identifier. If a non-zero value is entered into TaxRegionId, other fields will be ignored. Not recommended.

number
Array[Lines]
LineNo
Required

Line item identifier. LineId uniquely identifies the line item row.

string
DestinationCode
Required

Destination (ship-to) address code. DestinationCode references an address from the Addresses collection.

string
OriginCode
Required

Origination (ship-from) address code. OriginCode references an address from the Addresses collection.

string
ItemCode

Your item identifier, SKU, or UPC. Strongly recommended.

string
TaxCode

Product taxability code of the line item. Can be an AvaTax system tax code, or a custom-defined tax code.

string
CustomerUsageType

The client application customer or usage type. CustomerUsageType determines the exempt status of the transaction based on the exemption tax rules for the jurisdictions involved. Can also be referred to as Entity/Use Code. More information about this value is available in the Avalara Help Center.

string
BusinessIdentificationNo

The buyer’s VAT id. Using this value will force VAT rules to be considered for the transaction. This may be set on the document or the line.

string
Description

Item description. Required for customers using our filing service.

string
Qty

Item quantity. The tax engine does NOT use this as a multiplier with price to get the Amount.

number
Amount

Total amount of item (extended amount, qty * unit price). If omitted, this value will default to 0

number
Discounted

Should be set to true if the document level discount is applied to this line item. Defaults to false.

boolean
TaxIncluded

Should be set to true if the tax is already included, and sale amount and tax should be back-calculated from the provided Line.Amount. Defaults to false.

boolean
Ref1

Value stored on a line item. Does not affect tax calclulation.

string
Ref2

Value stored on a line item. Does not affect tax calclulation.

string
TaxOverride
Reason
Required

This provides the reason for a tax override for audit purposes. Typical reasons include: 'Return', 'Layaway', 'Imported'.

string
TaxOverrideType
Required

Must be one of the following: None: Default TaxAmount: The TaxAmount overrides the total tax for the document. This is used for imported documents, returns, and layaways where the tax has already been calculated either by AvaTax or another means. Exemption: Exemption certificates are overridden making the document taxable. This may be used for situations where a normally exempt entity needs to be treated as not exempt. TaxDate: The TaxDate overrides the DocDate as the effective date used for tax calculation. This may effect rates, rules and other factors.

string
TaxDate

Must be valid date, required if TaxOverrideType is TaxDate, the override tax date to use. This is used when the tax has been previously calculated as in the case of a layaway, return or other reason indicated by the Reason element. If the date is not overridden, then it should be set to the same as the DocDate.

string
TaxAmount

Must be numeric, required if TaxOverrideType is TaxAmount. The overriding amount of tax to apply. If at the document level, this is distributed across all taxable rows.

string

Response

DocCode

While this is an optional field, serious consideration should be given to using it. If no value is sent, AvaTax assigns a GUID value to keep the document unique, which can make reconciliation a challenge.

string
DocDate

Date of invoice, sales order, purchase order, etc.

string
TimeStamp

Server timestamp of request.

string
TotalAmount

Sum of all line Amount values.

number
TotalDiscount

Sum of all TaxLine discount amounts.

number
TotalExemption

Total exemption amount.

number
TotalTaxable

Total taxable amount.

number
TotalTax

Sum of all TaxLine tax amounts.

number
TotalTaxCalculated

Indicates the total tax calculated by AvaTax. This is usually the same as the TotalTax, except when a tax override amount is specified. This is for informational purposes. The TotalTax will still be used for reporting.

number
TaxDate

Date used to assess tax rates and jurisdictions.

string
Array[TaxLines]
LineNo

Line item identifier.

string
TaxCode

The tax code used in calculating tax.

string
Taxability

Flag indicating item was taxable.

boolean
Taxable

The amount that is taxable.

number
Rate

Effective tax rate.

number
Tax

Tax amount.

number
Discount

Discount amount.

number
TaxCalculated

Amount of tax calculated.

number
Exemption

Exempt amount.

number
BoundaryLevel

The boundary level used to calculate tax: determined by the quality of provided addresses.

string
Array[TaxDetails]
Country

Two character ISO country code.

string
JurisName

Name of a tax jurisdiction.

string
JurisCode

State assigned code identifying the jurisdiction. Note that this is not necessarily a unique identifier of the jurisdiction.

string
JurisType
string
Rate

Effective tax rate for tax jurisdiction.

number
Region

Region of tax jurisdiction.

string
Tax

Tax amount

number
TaxName

Tax name

string
Array[TaxSummary]
Country

Two character ISO country code.

string
JurisName

Name of a tax jurisdiction.

string
JurisCode

State assigned code identifying the jurisdiction. Note that this is not necessarily a unique identifier of the jurisdiction.

string
JurisType
string
Rate

Effective tax rate for tax jurisdiction.

number
Region

Region of tax jurisdiction.

string
Tax

Tax amount

number
TaxName

Tax name

string
Array[TaxAddresses]
Address

Canonical street address

string
AddressCode

Reference code uniquely identifying this address instance. AddressCode will always correspond to an address code supplied to in the address collection provided in the request.

string
City

City name

string
Region

State or region name

string
Country

Country code, as ISO 3166-1 (Alpha-2) country code (e.g. "US")

string
PostalCode

Postal code

string
Latitude

Geographic latitude.

number
Longitude

Geographic longitude.

number
TaxRegionId

AvaTax tax region identifier.

number
JurisCode

Tax jurisdiction code.

string
ResultCode

Classifies severity of message. One of: Success, Warning, Error, Exception

string
Try Calculate Tax and Record a Document now!

Input

Fill with Sample Data
Reset
Show all request attributes

Post Body

Addresses

item 1

Add Addresses

Lines

item 1

Add Lines
Reset
API Endpoint
https://development.avalara.net/1.0/tax/get
Method
POST
Request
{
  "Addresses": [
    {}
  ],
  "Lines": [
    {}
  ]
}
Response
 

Void a Document

Voids or deletes and existing transaction record from the AvaTax system. To use the XML for this operation specify the request Content-Type: text/xml. No modification needs to be made to the URL.

Api Endpoint
POST https://development.avalara.net/1.0/tax/cancel

Headers
Authorization: Basic aHR0cHdhdGNoOmY=Content-Type: text/json,text/xml

Post Body Parameters

CancelCode
Required

The reason for cancelling the tax record. One of: Unspecified, PostFailed, DocDeleted, DocVoided, AdjustmentCancelled

string
CompanyCode
Required

Client application company reference code. Not required if the document is identified by DocId.

string
DocCode
Required

Client application identifier describing this tax transaction (i.e. invoice number, sales order number, etc.). Not required if the document is identified by DocId.

string
DocType
Required

Value describing what type of tax document is being cancelled. One of: SalesInvoice, ReturnInvoice, PurchaseInvoice. Not required if the document is identified by DocId.

string
DocId

Avatax-assigned unique Document Id, can be used in place of DocCode, DocType, and CompanyCode.

string

Response

CancelTaxResult
TransactionId

The unique numeric identifier of the API operation assigned by the AvaTax service.

string
DocId

The unique numeric identifier (Document ID) assigned to the tax document in question by the AvaTax Service.

string
ResultCode

Classifies severity of message. One of: Success, Warning, Error, Exception

string
Array[Messages]
Summary

The message summary in short form.

string
Details

Description of the error or warning.

string
RefersTo

The data used during the request that caused the message to be generated.

string
Source

The internal location that generated the message.

string
Severity

Classifies the severity of the message. One of: Success, Warning, Error, Exception.

string
Try Void a Document now!

Input

Fill with Sample Data
Reset
Show all request attributes

Post Body

Reset
API Endpoint
https://development.avalara.net/1.0/tax/cancel
Method
POST
Request
{}
Response
 

Estimate Tax

Retrieves tax rate details for the supplied geographic coordinates and sale amount. Since the REST API does not provide an explicit ping function, this method can also be used to test connectivity to the service. If you would like an XML response, use the URL /1.0/tax/{latitude},{longitude}/get.xml and specify the request header Content-Type: text/xml.

Api Endpoint
GET https://development.avalara.net/1.0/tax/{latitude},{longitude}/get

Headers
Authorization: Basic aHR0cHdhdGNoOmY=

Querystring Parameters

saleamount
Required

The amount of sale requiring tax calculation, in decimal format

string

Path Parameters

latitude
Required

The latitude of the geographic coordinates to get tax for based on the sale amount

string
longitude
Required

The longitude of the geographic coordinates to get tax for based on the sale amount

string

Response

Rate

Total effective tax rate.

number
Tax

Total calculated tax amount.

number
Array[TaxDetails]
Country

Two character ISO country code.

string
JurisName

Name of a tax jurisdiction.

string
JurisCode

State assigned code identifying the jurisdiction. Note that this is not necessarily a unique identifier of the jurisdiction.

string
JurisType
string
Rate

Effective tax rate for tax jurisdiction.

number
Region

Region of tax jurisdiction.

string
Tax

Tax amount

number
TaxName

Tax name

string
ResultCode

Classifies severity of message. One of: Success, Warning, Error, Exception

string
Try Estimate Tax now!

Input

Fill with Sample Data
Reset

Path Parameters

Query String

API Endpoint
https://development.avalara.net/1.0/tax/{latitude},{longitude}/get
Method
GET
Request
curl -X GET "https://development.avalara.net/1.0/tax/{latitude},{longitude}/get" -H "Accept: application/json" -H "Authorization: Basic aHR0cHdhdGNoOmY="
Response
 

Validate an Address

Normalizes a single US or Canadian address, providing a non-ambiguous USPS address match. To recieve an XML response, use the URL /1.0/address/validate.xml and set the request header Content-Type: text/xml

Api Endpoint
GET https://development.avalara.net/1.0/address/validate

Headers
Authorization: Basic aHR0cHdhdGNoOmY=

Querystring Parameters

Line1
Required

Address line 1

string
Line2

Address line 2

string
Line3

Address line 3

string
City

City name: optional unless PostalCode is not specified.

string
Region
string
Country
Required
string
PostalCode
string

Response

Address
Line1

Address line 1

string
Line2

Address line 2

string
Line3

Address line 3

string
City

City name

string
Region

State, province, or region name.

string
Country

Country code.

string
PostalCode

Postal or ZIP code

string
AddressType

Address type code. One of: * F - Firm or company address * G - General Delivery address * H - High-rise or business complex * P - PO Box address * R - Rural route address * S - Street or residential address

string
FipsCode

FIPSCode is a unique 10-digit code representing each geographic combination of state, county, and city. The code is made up of the Federal Information Processing Code (FIPS) that uniquely identifies each state, county, and city in the U.S. Returned for US addresses only. Digits represent jurisdiction codes: * 1-2 State code * 3-5 County code * 6-10 City code

string
CarrierRoute

CarrierRoute is a four-character string representing a US postal carrier route. The first character of this property, the term, is always alphabetic, and the last three numeric. For example, “R001” or “C027” would be typical carrier routes. The alphabetic letter indicates the type of delivery associated with this address. Returned for US addresses only. * B - PO Box * C - City delivery * G - General delivery * H - Highway contract * R - Rural route

string
PostNet

POSTNet is a 12-digit barcode containing the ZIP Code, ZIP+4 Code, and the delivery point code, used by the USPS to direct mail. Returned for US addresses only digits represent delivery information: * 1-5 ZIP code * 6-9 Plus4 code * 10-11 Delivery point * 12 Check digit

string
ResultCode

Classifies severity of message. One of: Success, Warning, Error, Exception

string
Try Validate an Address now!

Input

Fill with Sample Data
Reset

Query String

API Endpoint
https://development.avalara.net/1.0/address/validate
Method
GET
Request
curl -X GET "https://development.avalara.net/1.0/address/validate" -H "Accept: application/json" -H "Authorization: Basic aHR0cHdhdGNoOmY="
Response