If you're onboarding to AvaTax or migrating from another system, you need to get past transactions into Avalara so your records are complete and your returns reconcile. This article walks you through downloading the import template, filling in the required fields, uploading historical data, and verifying the import status in AvaTax.
Quick answer
- Download the standard transaction template from Transactions > Import transactions in AvaTax, then fill in the required fields for each transaction row (ProcessCode, DocCode, DocType, DocDate, CustomerCode, LineNo, Amount, origin and destination regions and postal codes).
- Upload the completed .csv or .xls file to AvaTax, and the system processes the transactions in bulk without updating your business application.
- Check Transactions > Transaction import history to confirm the import completed successfully or to download error and results files if issues occurred.
Before you start
Make sure you have the historical transaction data ready, including invoice numbers, transaction dates, line item amounts, customer codes, and origin and destination addresses. You'll also need access to AvaTax with permissions to import transactions.
Importing works in one direction only: it adds or adjusts transactions in Avalara, but it does not update the data in your business application. If you're using an Avalara Connector or Extractor that imports transactions automatically, you typically don't need to import historical data manually unless your business application doesn't contain the older records.
Download the standard transaction template
Start by downloading the Avalara-provided import template, which includes the required fields and structure AvaTax expects.
- From Avalara Home, go to Transactions > Import transactions.
- From the Template list, choose Standard transaction template.
- Select a .csv or .xls file format to download the template to your computer.
The template file is also available through the legacy import path at Transactions > Import transactions (legacy), where you can select Download the transaction import toolkit. This downloads a file called TransactionImportToolkit.zip. Right-click the file, select Extract All, and then open either ImportTransactionsTemplate.xlsx or ImportTransactionsTemplate.csv.
Both versions of the template require the same core fields.
Fill out the required fields
Open the downloaded template and add a row for each historical transaction. The required fields are:
Required transaction import fields
| Field | What it is | Format or value |
|---|---|---|
| ProcessCode | Action Avalara takes on the transaction | Use 3 for new transactions |
| DocCode | Unique ID for the invoice, credit memo, or return | Your internal document number |
| DocType | Type of tax document | 0 = Sales order, 1 = Sales invoice, 2 = Purchase order, 3 = Purchase invoice, 4 = Return order, 5 = Return invoice, 6 = Inventory transfer order, 7 = Inventory transfer invoice, 8 = Reverse charge order, 9 = Reverse charge invoice, 10 = Customs invoice, 11 = Customs order |
| DocDate | Transaction document date | yyyy-mm-dd or mm/dd/yyyy |
| CustomerCode | Customer ID from your business application | Your internal customer code |
| LineNo | Transaction line number | Numeric |
| Amount | Total sale for the line item | Numeric |
| OrigRegion | State or province abbreviation for origin | Two-letter code |
| DestRegion | State or province abbreviation for destination | Two-letter code |
| OrigPostCode | ZIP or Canadian postal code for origin | Standard postal code format |
| DestPostCode | ZIP or Canadian postal code for destination | Standard postal code format |
If you're enrolled in a Streamlined Sales and Use Tax Agreement (SST) program or have transactions from outside the U.S. or Canada, the required fields are different. See Avalara's Import transactions template guidelines for details.
If you have a location-based filing requirement, add the location code to the appropriate column in the template.
Save the file once you've completed all rows.
Upload the completed template to AvaTax
Once your template is filled out, upload it to AvaTax to import the historical transactions.
- Go to Transactions > Import transactions in Avalara.
- Drag and drop the completed template file to the area in the center of the page, or select Browse and choose the file from your computer.
- Wait for the import to complete. The time this takes depends on the size of your file.
After the upload finishes, a record of the import appears at Transactions > Transaction Import History.
Verify the import status
After uploading, check the import status to confirm the transactions went through successfully or to identify any errors.
- From Avalara Home, go to Transactions > Transaction import history.
- Find the import record in the list. Each row represents one import file.
- Check the IMPORT STATUS column for that record.
You'll see one of three statuses:
Import status and troubleshooting
| Status | What it means | What Avalara provides |
|---|---|---|
| Completed | All transactions imported successfully | Results file in the RESULTS column with all imported transaction records |
| Import failed | The entire import failed | Error file in the ERRORS column explaining the failure reason |
| Imported with errors | Some transactions imported, others had issues | Both a results file (successful transactions) and an error file (failed transactions) |
Download the error file if the import failed or had errors. The file lists the specific rows and reasons for each failure, so you can correct the data and re-upload.
Common issues and fixes
- Required field is missing or formatted incorrectly: Check that every required field is filled in for each row and that dates follow the yyyy-mm-dd or mm/dd/yyyy format. State codes must be two letters, and numeric fields like Amount and LineNo cannot contain text.
- Duplicate DocCode: Each DocCode must be unique unless you're updating an existing transaction. If you're adding new historical transactions, make sure no DocCode matches one already in AvaTax.
- Wrong DocType number: Double-check that the DocType number matches the transaction type. For example, a sales invoice should be 1, not 0 (which is a sales order).
- Import takes longer than expected: Large files with thousands of rows take more time to process. If the import status stays blank for more than a few minutes, refresh the Transaction import history page.
Expert tip: Run a trial import with a few records first
Before importing thousands of transactions, test the process with a small sample of records to familiarise yourself with the template and catch formatting errors early. This prevents large-scale import failures and saves time correcting issues across an entire file.
Reconciling historical transaction data before filing is equally important, as incomplete or mismatched records can create errors in your returns.
How Galvix can help with transaction data and filing
Importing historical transactions into AvaTax can be time-consuming, especially when you're dealing with missing fields, duplicate records, or failed uploads. Even after the import is complete, someone still needs to check that the transaction data matches your accounting records before filing.
If your finance team is spending too much time preparing sales data and reconciling returns, Galvix can take that ongoing compliance work off their plate. Our team works with data from your billing and accounting systems, reconciles transactions, prepares sales tax returns, and files them after your approval. You can track everything through a dashboard without managing the filing process yourself.
Book a demo to see how Galvix can help manage your sales tax compliance.
FAQ
Can I import transactions from before I started using AvaTax?
Yes. The import template accepts transactions from any date, so you can bring in historical invoices and purchase orders to complete your records or reconcile returns that cover periods before your AvaTax implementation.
Does importing transactions update my accounting system or ERP?
No. The import only adds or adjusts transaction data in Avalara. It does not write back to your business application, so any changes you make in the import file stay in AvaTax only.
What happens if I upload the same transaction twice?
If the DocCode already exists in AvaTax and you use ProcessCode 3 (which is for new transactions), the import will fail for that row. To update an existing transaction, use a different ProcessCode. Check Avalara's Import transactions template guidelines for the full list of ProcessCodes and what each one does.
Do I need to import transactions if I use an Avalara Connector or Extractor?
Typically no. Connectors and Extractors import transactions automatically from your business application or marketplace. You only need to import manually if your integration doesn't cover certain historical periods or if you have transactions outside the connected system.
Can I import marketplace transactions like Amazon or eBay using this template?
Yes, but if the marketplace collects and remits tax on your behalf, you'll want to set up custom rules in AvaTax to exclude those transactions from your liability reports. Create marketplace locations first at Settings > Company locations, then add a custom rule at Settings > Rules > Custom rules to prevent double-reporting. For more details, see Avalara's guidance on tracking marketplace transactions.
