Guides
File Upload
File upload imports sales transactions from a CSV, which is the fastest way to bring in history when you are onboarding or backfilling a period. Uploaded transactions behave exactly like ones created through the API: they count toward nexus, feed compliance reporting, and land on the right return at filing time.
This page is the column reference. Download the template from the app, or with Download a CSV import template, then use the tables below to fill it in.
CSV column names are snake_case, such as transaction_external_id. They describe the file, not the API, so they do not change to camelCase on the Tenanted API. The camelCase names appear only in API responses, such as the resultData rows that Validate a CSV file returns.
Before You Start
Five columns have to be in the fileA file missing any of these is rejected before any row is read. The first four need a value on every row. amount is required as a column so that a file without it cannot book every line at 0.00. Every other column can be left out entirely, and the value falls back to the default listed on its row. Leaving one out is not the same as including it and leaving cells blank, which the next two cards cover.
transaction_external_iddatecustomer_idproduct_external_idamount
Omitting a column is safe. Blanking a cell is notA default only applies when the column is absent from the file. Once you include a column, the upload validator expects a value in it, and it is stricter than the defaults suggest.
Column absentThe documented default applies to every row. This is the safe way to skip a column you have no data for.
Column present, cell emptyRejected for operation, and a conflict on any transaction-level column where another row of the same transaction does carry a value. Delete the column, or fill it in on every row.
One transaction, many rows, identical valuesA multi-line sale is several rows sharing one transaction_external_id. Only the line item columns are allowed to differ between them. Every transaction-level column you include has to carry the same value on every row, including the addresses, the buyer, the date, status, currency, transaction_type and operation.Filling a column in on the first row and leaving it blank on the rest is the most common way to trip this, because an empty cell counts as a different value. The error names the column and the row it first saw: Inconsistent 'transaction_type': '' vs 'SALE'.
Save the file as text, not as a spreadsheetFormat every cell as General before exporting. A cell typed as Date or Number is re-serialized on save, which is the most common reason a file that looks correct fails validation. Postal codes are the other one: a leading zero has to survive the export.
Reading the badges
RequiredA value in every row.
ConditionalRequired in a stated case. The rule is on the row.
OptionalLeave the column out and the default applies.
The downloadable template carries two columns the importer does not read. total_amount is ignored because transaction totals come from the line items, so fill in amount and tax_amount per row instead. source is ignored too: each transaction takes its source from the import itself.
On the Tenanted API, an import's source is the source you send to the Imports endpoints, and it reads back as transactionSource.
Transaction Columns
These describe the sale. Every row of a multi-line sale repeats them, and rows sharing a transaction_external_id are read as line items of one transaction.
Identity, type and date9 columns
transaction_external_idRequired
Your own id for the transaction. Kintsugi keys the record on it.
e.g.in_ctvrAUrbiRdSywvQ
Unique per transaction. Rows sharing an id are read as line items of the same sale.related_external_idConditional
The original transaction's id, when this row credits an earlier sale.
e.g.PCR_ctvrAUrbiRdSywvQ
Required when transaction_type is FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE. A row cannot reference itself.transaction_typeOptional
What kind of transaction the row represents.
e.g.SALE
Accepted values
Both credit-note types require related_external_id. Transaction-level, so every row of a multi-line sale needs the same value.SALEFULL_CREDIT_NOTEPARTIAL_CREDIT_NOTETAX_REFUND
statusOptional
Where the transaction sits in its lifecycle.
e.g.COMMITTED
Accepted values
INVALID and ARCHIVED are set by Kintsugi and rejected on import. Transaction-level, so repeat it on every row of a multi-line sale.COMMITTEDPENDINGCANCELLEDFULLY_REFUNDEDPARTIALLY_REFUNDED
operationConditional
What the importer should do with the row.
e.g.IMPORT
Accepted values
Required as soon as the column is in the file. A blank cell is rejected outright rather than falling back to IMPORT, so leave the column out or fill it in on every row.IMPORTUPDATEARCHIVE
dateRequired
When the transaction took place.
e.g.2024-03-23T00:00:00
Format the cell as General. A cell typed as Date is rewritten on save and the row fails.currencyOptional
Currency for every amount on the row.
e.g.USD
Transaction-level, so repeat it on every row of a multi-line sale.descriptionOptional
Free text describing the transaction.
e.g.Heirloom Ring Size 8.5 14K
marketplaceOptional
Whether a marketplace facilitator collected the tax on this sale.
e.g.FALSE
The buyer5 columns
customer_idRequired
Your own id for the buyer. Exemptions attach to it.
e.g.cust_cCMVtrsfoUV
Transaction-level, so every row of a multi-line sale needs the same buyer.customer_nameOptional
The buyer's full name.
e.g.Faith Ortega
customer_emailOptional
The buyer's email address.
e.g.michele45@example.com
customer_company_nameOptional
The buyer's registered or legal business name.
e.g.Example Company Inc.
tax_idOptional
The buyer's registration number.Transaction-level, so every row of a multi-line sale needs the same value.
Address Columns
Addresses decide the rate, so this is the part of the file worth checking twice. A postal code resolves to a local jurisdiction; a state on its own does not.
The one ruleEvery row needs a postal code and a country from one side or the other. Which side is up to you, but you cannot leave both empty.
Eithership_to_postal_code + ship_to_country
Orbill_to_postal_code + bill_to_country
Ship to7 columns
ship_to_countryConditional
The recipient's country.
e.g.US
Required unless bill_to_postal_code and bill_to_country are both present. A country of PR is read as state PR in the US.ship_to_postal_codeConditional
The recipient's postal code. This is what resolves the local rate.
e.g.21830
Checked when the country is US or blank. A 4-digit code is accepted and gets its leading zero back, but exporting the column as text is safer.ship_to_stateOptional
The recipient's state or province.
e.g.CO
ship_to_cityOptional
The recipient's city.
e.g.Aurora
ship_to_street_line_1Optional
First line of the street address.
e.g.811 Eric Flat Suite 183
ship_to_street_line_2Optional
Second line of the street address.
e.g.Apt 1606
ship_to_phoneOptional
The recipient's phone number.
e.g.+1 665-869-8307
Bill to7 columns
bill_to_countryConditional
The billed party's country.
e.g.US
Required unless ship_to_postal_code and ship_to_country are both present. A country of PR is read as state PR in the US.bill_to_postal_codeConditional
The billed party's postal code. This is what resolves the local rate.
e.g.21830
Checked when the country is US or blank. A 4-digit code is accepted and gets its leading zero back, but exporting the column as text is safer.bill_to_stateOptional
The billed party's state or province.
e.g.CO
bill_to_cityOptional
The billed party's city.
e.g.Aurora
bill_to_street_line_1Optional
First line of the street address.
e.g.811 Eric Flat Suite 183
bill_to_street_line_2Optional
Second line of the street address.
e.g.Apt 1606
bill_to_phoneOptional
The billed party's phone number.
e.g.+1 665-869-8307
Line Item Columns
One row per line item. The product columns drive classification, and the money columns are what your filings reconcile against.
The product and the money10 columns
product_external_idRequired
Your own id for the product, usually the SKU.
e.g.F80-BRW
product_nameOptional
The product's name.
e.g.Product Name 9
product_descriptionOptional
The product's description.
e.g.Product Description 9
line_item_idOptional
Your own id for this line of the transaction.
e.g.il_lQtcAcqhLGPQZhSa
amountConditional
What this line came to, after discounts and excluding tax.
e.g.550.51
The column has to be in the file. Transaction totals are summed from these, so this is the figure that has to reconcile.tax_amountOptional
Tax collected on this line.
e.g.1.69
quantityOptional
How many units this line covers.
e.g.14
discount_amountOptional
Discount applied to this line.
e.g.0.69
When present it has to be greater than 0 and no more than amount. Since amount is already net of discounts, this column records the discount rather than applying it.exemptOptional
Whether this line is exempt from tax.
e.g.FALSE
customer_exemptOptional
Whether the buyer holds an exemption covering this sale.
e.g.FALSE
Cannot be TRUE when exempt is also TRUE: the row has to say whether the product or the buyer is the reason.product_name and product_description are optional columns that do real work: Kintsugi classifies the product from them, and classification is what decides taxability per state. A file with bare SKUs imports cleanly and prices badly.
Importing a Refund
A refund is a credit note row that points at the original sale.
Mark the row as a credit note
Set transaction_type to FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE. That is what makes the next column required.
Point it at the original
Put the original sale's id in related_external_id, and give the credit note its own transaction_external_id. A row cannot reference itself.
PCR_Credit note ids are conventionally the original id behind a PCR_ prefix, which keeps the pair legible in an export.
Set the original's status
PARTIALLY_REFUNDED and FULLY_REFUNDED are both accepted values of status, for the original sale's rows.
Recording refunds through the API instead? See Handling Refund Transactions.
After the Upload
Kintsugi validates the file before importing any of it, and errors come back per row and per column, so a rejected file tells you which cell to fix rather than just failing.
The same checks are available through the Tenanted API's Imports endpoints:
- Validate a CSV file checks a file's contents before you upload it. It always answers
200; readisValidanderrorsto see whether the file passed. - Get an import by id reports an import's
statusand its row counts, includingvalidRowCountandinvalidRowCount. - Get a download link for an import's error artifact returns the validation errors as a file, or the row-processing errors with
phase=import. - Import the validated rows imports the rows that passed.
submitModeALLrequires every row to have passed validation;VALID_ONLYimports the rows that passed and skips the rest.
Related Resources
Getting Started
Set up your account and import historical data.
Syncing Transaction Records
Prefer automation? Sync transactions programmatically instead.
Migrating from Avalara or TaxJar
Moving providers? CSV upload is usually the fastest way to backfill history.
Product Categories
How Kintsugi classifies products, which is what the product columns feed.