Importing Data with a Spreadsheet
In this article
- How to import data into TaxJar
- How to upload and manage your spreadsheet files
- Should I use the Line Item Template vs Order Template?
- Formatting guidelines: Line Item Template
- Formatting guidelines: Order Template
- How to fix errors in spreadsheet uploads
- More FAQs for uploading your spreadsheet file
- How to edit transactions
- How do I delete line items from an Order?
- How to remove a Spreadsheet file from your TaxJar account
How to import data into TaxJar
We first recommend checking if your sales channel is supported in your Linked Accounts.
- You'll need an active TaxJar subscription to access this link.
- You can also upload a file here in your Transactions:
How to upload and manage your spreadsheet files
1) Visit the Linked Accounts page and click on "Upload a CSV"
2) Click "Choose File" to select your file and "Upload spreadsheet" to select the spreadsheet.
- If you receive an error message that we were not able to import rows in your spreadsheet, that means one or more of the values in your spreadsheet is not formatted to match the values our system will accept in an import.
- To resolve this error and make sure your import is successful, we offer formatting guidelines for the requested values.
From your Linked Accounts page, go to "Manage CSV Files to view all your previous imports and file import status. You can also directly upload from here by clicking "Upload Spreadsheet".
Should I use the Line Item Template vs Order Template?
While all TaxJar customers can use both templates, line items are a way for you to communicate more details about the items in your order.
- We share more detail here about why you should send line items.
- By passing in line items, you can use product_tax_codes to communicate to TaxJar what type of products are included in an order.
- We strongly recommend using the Line Item Template to ensure your TaxJar Reports accurately reflect your data. If you use the Order Template, please be aware your products may be missing necessary product tax code information that impacts your sales tax reports.
Formatting Guidelines for Line Item Template
If you upload using the Order template, please follow the Orders template formatting guidelines. These two templates are not interchangeable.
TaxJar accepts two spreadsheet formats: CSV and XLSX. The older XLS format is not accepted.
- We support Windows 1252, ISO-8859-1, UTF-8, UTF-16, and UTF-32 encodings, but please prefer UTF-8 encoding to avoid any garbled text. Excel 2007 and later will save XLSX files as UTF-8 by default. If you're exporting CSV, then Excel will save it as Windows 1252 encoding. All other software should prefer to encode CSVs in UTF-8 to avoid any ingestion issues.
- If you're unsure or having issues uploading your file, please export and/or save as CSV as that will always be the most efficient method to clean up any file type extensions and import your data.
If the from_* values are not complete, your reports will default to the state's address if one is entered; if not, then it will default to your business profile address (if you're a remote seller).
Please use lowercase to map to known providers (ie: “ebay” and “amazon”)
If the sale is conducted in-store or via an unsupported platform, then any unique keyword can be input: (ie: mycart, instore, popupshop, cash).
|transaction_id|| Required. Alphanumeric. Unique.
Re-using the same transaction_id will over-write the previous order uploading additional CSVs!
|transaction_type|| Recommended: Empty defaults to “Order”
Accepts “Order” or “Refund”.
All values for "refunds" are negative and that all values for "orders" are positive.
|transaction_reference_id|| Required for Refund Transactions. Link refunds to the original order by filling in the order’s transaction_id here.
Requirement: Needs rows with
|transaction_date|| Required. Please use the ISO-8601 format in either Date or Date-Time (YYYY-MM-DD).
Cannot be in a future year. Other date formats can be used, however, ISO-8601 will always be parsed correctly.
|to_state|| Required. Use 2-letter codes. (eg: NY, NC)
|to_zip|| Required if US address
|to_country||Required. Use 2-letter country codes (eg: US, CA)|
|from_state|| Recommended. Use 2-letter codes (eg: NY, NC)
Use 2-letter country codes (eg: US, CA)
|total_shipping||If not provided or is 0 and line item shipping is provided, then we will calculate automatically based on provided line items.|
|total_handling||If not provided or is 0 and line item handling is provided, then we will calculate automatically based on provided line items.|
|total_sales_tax|| If not provided or is 0 and line item sales tax is provided, then we will calculate automatically based on provided line items.
**If you see an error about the total_sales_tax not matching, please see below here.
|item_product_identifier||Required. This can be a unique code used to identify the product, such as a SKU or part number.|
|item_quantity|| Must be positive and a whole number, even on refunds.
Empty defaults to 1.
|item_shipping|| Empty defaults to 0. If provided alongside
|item_handling|| Empty defaults to 0. If provided alongside
|item_discount||Empty defaults to 0|
|item_sales_tax|| Empty defaults to 0. If provided alongside
|item_product_tax_code|| If provided, then
|| You can denote exempt transactions via spreadsheet upload for marketplace facilitators, wholesale or resale, or government or exempt entities.
Why did some of my Transactions fail to upload?
If you receive an error message that there were Failed Transactions in your spreadsheet, you can find out why those rows did not successfully import in your Spreadsheet Imports page.
- Click the number in the "Failed Rows" column for the file that you just tried to import:
This will allow you to download a spreadsheet with an additional column titled "errors" that will show you the reason the Transaction did not upload:
- We offer examples of common transaction errors in your TaxJar account.
PLEASE BE SURE NOT TO USE THIS FILE AS A TEMPLATE.
To fix the file and import the Failed Transactions:
- Use the information in the 'errors' column to correct each of the Failed Transaction details according to our guidelines above.
- Delete the "errors" column and upload the file again.
Specific Errors for line item spreadsheet
- If you receive this error:
Order-level fields are different among line itemsthen each row (line item) has both a line item field and an order field. Please review and remove either the line item fields or order fields.
- If you receive this specific error:
total_sales_tax does not match expected <value> from line_itemsthen your total_sales_tax does not equal the sum of your item_sales_tax.
To correct, please choose one of the following options:
- a) Do not pass any values for item_sales_tax for each line item in that order. We'll automatically distribute the total_sales_tax among those line items
- b) Manually distribute the remaining sales tax from shipping across all of their line item rows in the item_sales_tax so that the total_sales_tax and sum of the item_sales_tax rows are equal
How can I edit or fix my transactions?
You can edit details for transactions previously imported via spreadsheet or a direct account connection by uploading a spreadsheet with the details you'd like displayed in TaxJar for the order(s) you need to edit.
- We discuss how to do this in more detail here.
How do I delete line items from an Order?
If you are updating existing transactions, we show you how to do this here by uploading a spreadsheet file by ensuring the
transaction_id values remain the same.
- In the Order, if you do not include the same line items that were uploaded originally, then any line items that are not included when uploading a CSV to edit an Order, will be deleted.
- If you wish to delete line items from an Order, then you simply exclude them when uploading the CSV to edit and correct your existing transactions.