Batch File Reference

Batch File Reference

You probably already know how to use CreateTransaction to calculate tax for one transaction at a time. The main difference here is that we’ll be uploading a file with tons of individual transactions in it.

Batch File Limitations

  • A batch file may have up to 100,000 lines. Any batch file with more than 100,000 lines may be rejected.
  • Batch files must be in XLS, XLSX, or CSV formats.
  • When using Excel, please be careful about scientific-notation conversion. Excel may choose to convert some large numbers to scientific notation; this is especially problematic for UPC codes which often look like large numbers. Please be careful when using Excel and ensure that the final file does not have conversion problems.
  • Batch files are processed by AvaTax in the order they were received.

These are the REST v2 supported Batch File Types

Download CSV Batch Templates:

  • ItemImport - refers to a batch type used for uploading multiple items and their respective tax codes at once.
  • CompanyLocationImport - refers to a batch type used to upload multiple company locations at once.
  • ExemptCertImport - refers to a batch type used to upload all relevant data for multiple exemption certificates at once.
  • TaxRuleImport - refers to a batch type used to upload all relevant information for multiple tax rules at once.
  • TransactionImport - refers to a batch type used for uploading multiple transaction lines at once.
  • UPCBulkImport - refers to a batch type used for uploading multiple UPC codes and their respective tax codes at once.

Sample File

As an example let’s upload some transaction lines, to get satarted quickly download the TransactionImport template and enter in the following data.

List of Required Fields

The following column fields correspond to the same fields in the CreateTransactionModel and are supported in batch files. You must fill in, at a minimum, data for these columns in the batch file:

Field Data Type Definition Sample Values
ProcessCode Whole number, 1 digit This field determines how Avalara AvaTax processes the document. Here are the process codes that you can use and what they mean: 0: Void transaction 1: Tax override--a new transaction without tax calculation 2: Tax override--adjusted transaction without tax calculation 3: New transaction 4: Adjust current transaction 5: Accrued tax override--new transaction without tax calculation that provides an accrued tax amount, typically used for customer use tax 6: Accrued tax override--adjusted transaction without tax calculation that provides an accrued tax amount, typically used for customer use tax Note: -ProcessCode 0 requires the DocCode, DocType, and CompanyCode of the current document to be voided. No other column values are required for a voided transaction. -For ProcessCodes 1 or 2 that override tax, enter the tax amount desired in the TotalTax column (column AP). -For ProcessCodes 5 and 6 that override tax, enter the accrued tax amount desired in the TotalTax column (column AP) and enter 0 in the Amount column (column N). 
3
DocCode Alphanumeric string, up to 50 places The invoice, credit memo, or return number. It must be unique at the company level 
12345-6789-ABCDEF
DocType Whole number, 1 digit The type of document: 1=Sales invoice 3=Purchase invoice 5=Return invoice 7=Inventory Transfer invoice 
1
DocDate Date, up to 10 digits The invoice, credit memo, or return date in yyyy-mm-dd or mm/dd/yyyy format. Use the format that most closely matches the one in your accounting, ERP, e-commerce, or point-of-sale software, but dates must be in mm/dd/yyyy or yyyy-mm-dd format: 12/30/2012 = mm/dd/yyyy 2012-12-30 = yyyy-mm-dd 
2016-10-24
CustomerCode You must put something in this column, and it must be in this format: Alphanumeric, up to 50 characters This is the code that your accounting, ERP, e-commerce, m-commerce, or point-of-sale application uses to identify a customer; for example, the customer ID or customer number 
ABC
LineNo Text, up to 10 characters The line number of the transaction. LineNo for a transaction must uniquely identify each line on the document. We recommend sequential numbering: 1, 2, 3, 4, etc. 
1
Amount Number with up to 2 decimal places The total sale amount (extended amount) for the document line item (Quantity * Unit Price). Note: For return invoices (DocType 5, column C), enter the amount as a negative value. 
100.00
DestRegion Text, 2 characters The two-character abbreviation for the destination or ship-to state or province. If you enter something in LocationCode (column AD), leave DestRegion blank. 
CA
DestPostalCode Alphanumeric text, up to 10 characters The destination or ship-to postal code in one of these formats: 12345 (United States ZIP Code) 12345-6789 (United States ZIP+4 Code) A1B 2C3 (Canadian postal code) If you enter something in LocationCode (column AD), leave DestPostalCode blank. 
92615
OrigRegion Text, 2 characters The two-character abbreviation for the origin or ship-from state or province. If you enter something in LocationCode (column AD), leave OrigRegion blank. 
WA
OrigPostalCode Alphanumeric text, up to 10 characters The origin or ship-from postal code in the following format: 12345 (United States ZIP Code) 12345-6789 (United States ZIP+4 Code) A1B 2C3 (Canadian postal code) If you enter something in LocationCode (column AD), leave OrigPostalCode blank. 
92615
IsSellerImporterOfRecord Boolean Transaction for physical good are taxed differently when seller is importer or record or not.
Header_Description Text This is the sale description that will be displayed in the Service Invoice. (Discriminação do Serviço)

List of Optional Fields

The following fields correspond to the same fields in the CreateTransactionModel and are supported in batch files:

Field Data Type Definition Sample Values
CompanyCode Text, up to 25 characters The code used by Avalara AvaTax. To find out more, visit: https://help.avalara.com/004_AvaTax_Integrations/002_All_About_Company_Codes If you leave this company code blank, the transaction will be added to your default company. 
DEFAULT
EntityUseCode Text, up to 25 characters An entity use code triggers customer-level tax rules. Entity use codes for the United States and Canada are different. Avalara AvaTax supports custom codes and the following standard codes: A=Federal government (United States) B=State government (United States) C=Tribe/Status Indian/Indian Band (both) D=Foreign diplomat (both) E=Charitable or benevolent organization (both) F=Religious or educational organization (both) G=Resale (both) H=Commercial agricultural production (both) I=Industrial production or manufacturer (both) J=Direct pay permit (United States) K=Direct mail (United States) L=Other N=Local government (United States) P=Commercial aquaculture (Canada) Q=Commercial fishery (Canada) R=Non-resident (Canada) MED1=US MDET with exempt sales tax MED2=US MDET with taxable sales tax 
G
TaxCode Text, up to 25 characters The AvaTax tax code or custom tax code associated with the item or SKU used on the document line. TaxCode is not needed if ItemCode (column K) is mapped to a tax code in the AvaTax Website for your company. 
P0000000
TaxDate Date, 10 digits This optional parameter overrides the date used for sales tax calculation. Avalara AvaTax normally uses the DocDate (column D) for sales tax calculations. TaxDate is usually used on return invoice (credit memo) transactions that need a tax-calculation date that reflects the original invoice date and a transaction date that reflects the current reporting period. Use the date format that most closely resembles the date format used in your accounting, ERP, e-commerce, m-commerce, or point-of-sale application, but dates must be in mm/dd/yyyy or yyyy-mm-dd format: 12/30/2012 = mm/dd/yyyy 2012-12-30 = yyyy-mm-dd 
2016-10-24
ItemCode Text, up to 50 characters The item code or SKU that identifies the product, service, or charge. If ItemCode is mapped to an AvaTax System tax code or custom tax code in the AvaTax Website, importing a transaction that uses this field triggers system or custom tax rules. ItemCode is required only if the company (CompanyCode, column E) is in the Streamlined Sales Tax Project (SSTP) and the state of origin (OrigRegion, column AA) or destination (DestRegion, column V) is also in the SSTP. 
AB-124123DEF
Description Alphanumeric text, up to 255 characters A description of the document line item. Required when TaxCode (column I) is specified, if the company (CompanyCode, column E) is in the Streamlined Sales Tax Project (SSTP) and the destination (DestRegion, column V) is in an SSTP state. 
Dyed Wool Yarn (Red)
Qty Number with up to 4 decimal places The number of items on the document line, up to 4 decimal places (example: 1.3429. The default is 1. Note: Qty does not multiply the amount field. AvaTax uses Qty to calculate the per-item sales amount (unit price) for sales tax caps and thresholds. 
1
Discount Number, up to ?? digits The trade discount allocated to the document line that decreases the taxable or non-taxable amount. AvaTax handles discounts at the document header level. But when it imports transactions, it places discounts at the line level, and it treats discounts in this way: 1. Discounts applied at the line level in imported transactions are accumulated for the total document. 2. AvaTax redistributes the total discount by prorating the document discount amount across all the lines that had a discount amount assigned to them. Tax is calculated based upon the “new” prorated discount amount now found at the line level. Any lines on the document that did not have a discount remain at a $0 discount. 
15.00
Ref1 Alphanumeric text, up to 50 characters A user-defined field.
Ref2 Alphanumeric text, up to 50 characters A user-defined field.
ExemptionNo Text, up to 25 characters The exemption certificate number, if there is one. Putting a value in ExemptionNo generates a sales-tax exemption for the document line item to which the exemption certificate is applied. ExemptionNo is required if: -Exemption certificate options for the account are set to required. -You're a seller in a Simplified Sales Tax Program (SSTP) state and thus are required to use an exemption certificate management system to generate exemption certificates in SSTP states. 
12-345-6789
RevAcct Text, up to 25 characters The revenue account for this transaction. This field is user-defined to identify a general-ledger account.
DestAddress Alphanumeric text, up to 50 characters The destination or ship-to location's street address. If you enter something in LocationCode (column AD), leave DestAddress blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
123 Main Street
DestCity Text, up to 50 characters The destination or ship-to city. If you enter something in LocationCode (column AD), leave DestCity blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
Irvine
DestCountry Text, 2 characters The destination or ship-to country. If you enter something in LocationCode (column AD), leave DestCountry blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
US
OrigAddress Alphanumeric text, up to 50 characters The origin or ship-from street address. If you enter something in LocationCode (column AD), leave OrigAddress blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
100 Ravine Lane NE
OrigCity Text, up to 50 characters The origin or ship-from city. If you enter something in LocationCode (column AD), leave OrigCity blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
Bainbridge Island
OrigCountry Text, 2 characters The origin or ship-from country in two-character format. If you enter something in LocationCode (column AD), leave OrigCountry blank. If you don't enter something in LocationCode, fill in this field to ensure the most accurrate tax calculations. 
US
LocationCode Alphanumeric text, up to 50 characters The LocationCode identifies the sales location (outlet) for the document line. Use this field if you have set up that sales location's address in the AvaTax Website. 
DEF001
SalesPersonCode Alphanumeric text, up to 25 characters The salesperson for the document line. 
BOBEXAMPLE
PurchaseOrderNo Alphanumeric text, up to 50 characters The purchase order for the document line. Use this to match single-use exemption certificate entries created in the Exemption Certificate Management System (ECMS). 
PO20161024-001
CurrencyCode Text, 3 characters The ISO currency code; defaults to USD. 
USD
ExchangeRate Number, two digits seperated by decimal point The conversion rate from CurrencyCode to the company base currency--for reference only. The default is 1.0.
ExchangeRateEffDate Date, up to 10 digits The effective date of the exchange rate The default for ExchangeRateEffDate is the DocDate (column D). Use the format that most closely matches the one in your accounting, ERP, e-commerce, or point-of-sale software, but dates must be in mm/dd/yyyy or yyyy-mm-dd format: 12/30/2012 = mm/dd/yyyy 2012-12-30 = yyyy-mm-dd
TaxIncluded Whole number, 1 digit Indicates that tax is included in Amount (column N). AvaTax calculates the taxable (column AN) and TotalTax (column AP) amounts from this value. Use one of these: 1: Tax included in Amount (column N) 0 or blank: Tax not included in Amount (column N) 
0
ReferenceCode Text, up to 50 characters User-defined or for tracking merchant code for mobility reporting
BuyersVATNo Text, up to 25 characters The buyer's VAT registration number
Email Text Inform an email address for the buyer. The city tax authority may use this email to send the invoice confirmation directly to the buyer