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, then use the tables below to fill it in.
Before You Start
Four columns have to be in the fileA file missing any of these is rejected before any row is read. 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_id
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 total_amount and total_tax_amount columns that the importer does not read. Transaction totals are derived from the line items, so fill in amount and tax_amount per row and leave those two alone.
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 date10 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. A refunded status needs a matching credit-note row in the same file, or the refund cannot be processed. 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
sourceOptional
Where the data came from.
e.g.OTHER
The column is source. Kintsugi stores it as transaction_source, which is the name you will see on the transaction afterwards.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 buyer4 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.
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.ship_to_postal_codeConditional
The recipient's postal code. This is what resolves the local rate.
e.g.21830
Keep a leading zero. Kintsugi restores one for a probable US code, 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.bill_to_postal_codeConditional
The billed party's postal code. This is what resolves the local rate.
e.g.21830
Keep a leading zero. Kintsugi restores one for a probable US code, 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
amountOptional
What this line came to, after discounts and excluding tax.
e.g.550.51
Negative amounts are only valid on a credit note. 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 less 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 two rows: the credit note, and the original sale carrying an updated status.
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.
Update the original's status
Set the sale's status to PARTIALLY_REFUNDED or FULLY_REFUNDED in the same file.
A refunded status with no matching credit note cannot be processed. If you set FULLY_REFUNDED on a sale and send no credit-note row, the refund does not reach your filings. The same rule applies through the API: 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.
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.