How to Upload Sales Transactions in Kintsugi
Learn how to upload sales transactions to Kintsugi via CSV: download the template, map required columns, and import historical or unsupported-platform data.Updated 21 days ago
Use File Upload when you want to bring sales data into Kintsugi yourself: migrating historical transactions from a previous system, backfilling a period, or reporting from a platform Kintsugi does not integrate with natively.
The whole process happens in the app. You pick your source, download a template, upload your file, and Kintsugi tells you on screen what came in and what did not. If any rows need fixing, you get a file back with the exact reason on each row, so you can correct it and upload again without waiting on anyone.
Time required: about 15 minutes for a file that is already close to the template
You will need: your Kintsugi login, and your sales data exported as a CSV or XLSX file
Should you use File Upload or an integration?
If your sales platform is on Kintsugi's supported integrations list (Shopify, Stripe, NetSuite, QuickBooks, Amazon, and others), connect it directly instead. A connected integration keeps syncing on its own, so you never have to repeat this process.
File Upload is the right choice when:
Your platform has no native integration
You need a one-time historical import, for example to calculate nexus or tax exposure at a point in time
You need to load older transactions that sit outside an integration's sync window
To check what is available, see Data Sources in Kintsugi.
Step 1: Access the File Upload tab
Login to Kintsugi.
Navigate to Data Sources.
Select File Upload tab.
The tab has two sections, and both stay on screen the whole time. The upload area sits at the top. Upload History sits underneath it, so you can check an earlier upload without losing your place in a new one.
Step 2: Select your source
In Select Source, choose the platform your transaction data originally came from.
If your platform is not in the list, choose Other. This does not change how your data is processed.
Choose your source first. The file field stays inactive until a source is selected, because Kintsugi tags every row with where the data came from.
Then, click Download Template to get the template.
Always start from this template rather than reformatting your own export. It gives you the exact column headers Kintsugi expects, in the order Kintsugi expects them, and it marks the required columns for you. Starting from the template prevents most upload errors before they happen.
Step 3: Fill in your File
Map your own data into the template columns, then save the file as CSV or XLSX.
A few rules that matter:
Do not rename, remove, or reorder the columns. Column headers are case sensitive.
Do not leave a required column blank. An empty cell in a required column is treated as an error, not as a default value.
Save CSV files as UTF-8 so accented characters and symbols come through correctly.
Every row needs a complete enough address. At minimum, a postal code and a two-letter ISO country code. For US and Canadian addresses, the two-letter state or province code is required too. You can provide a ship-to address, a bill-to address, or both.
There are required fields that should be filled out accordingly. Check out the table below; required fields are marked in red. Missing any of them is the #1 cause of upload errors, so check these first if something doesn't go through.
Date Formatting Tip
Dates in the date column use the format YYYY-MM-DDTHH:MM:SS.
If you are working in Excel or Google Sheets, this formula converts a date cell to the right shape. Replace A2 with the cell holding your date:
=TEXT(A2,"YYYY-MM-DD") & "T" & TEXT(A2,"HH:MM:SS")You can include a UTC offset if you want to be precise about time zone, for example 2025-02-28T23:00:00-05:00. If you leave the offset out, Kintsugi reads the time as UTC. Either way, Kintsugi records the transaction under the local date it happened, which is the date that matters for filing.
Using the example above, Kintsugi stores:
Field | Value | Meaning |
|---|---|---|
| 2025-02-28 | Local transaction date |
| 2025-03-01 04:00:00 | UTC conversion |
| -05:00 | Local offset |
For a deeper walkthrough of every column, see this field-mapping reference sheet.
Column Reference
Use this table to map your data. Columns appear in template order.
| Required / Conditional / Optional) |
|
related_external_id | Conditional | The |
transaction_external_id | Yes | You unique ID for the transaction. Must only contain alphanumeric characters, underscores, and hyphens. |
status | Yes | Options: COMMITTED (default), PENDING, CANCELLED, FULLY_REFUNDED, PARTIALLY_REFUNDED, INVALID, ARCHIVED. Associated credit notes for refunds are required. Must not be left blank, as an empty string causes a validation error. |
date | Yes | Date the transaction occurred. Use standard date format YYYY-MM-DDT00:00:00. |
currency | Yes | Supports all ISO 4217 currency codes (USD, CAD, EUR, GBP, etc.). If not provided, defaults to USD. An empty string causes a validation error. |
description | Optional | Description of the transaction. Max 1000 characters. |
customer_id | Yes | Your unique ID for the customer. Must only contain alphanumeric characters, underscores, and hyphens. Max 100 characters. Reuse the ID the customer already has in Kintsugi so their totals stay on one record. |
customer_name | Optional | Name of the customer. Max 200 characters. |
customer_email | Optional | Email of the customer. Must be a valid email format. Max 200 characters. |
marketplace | Yes | TRUE if the sale went through a marketplace facilitator, FALSE if not. Do not leave blank. Default to false if missing; empty string causes validation error. |
ship_to_phone | Optional | Shipping address phone. Allows numerical values, space, "-", "+", "x." Max 50 characters. |
ship_to_street_line_1 | Optional | Shipping address line 1. Max 1000 characters. |
ship_to_street_line_2 | Optional | Shipping address line 2. Max 1000 characters. |
ship_to_city | Optional | Shipping city. Numerical values not allowed. Max 1000 characters. |
ship_to_state | Conditional | Shipping state. two-letter state abbreviation. Required if ship_to_country is US or CA, but not when you only provide the bill_to address. |
ship_to_postal_code | Conditional | Shipping postal code. Must use an accurate postal code based on the state and should match the state. Required if bill_to_postal_code and bill_to_country are empty. |
ship_to_country | Conditional | Shipping country. Two-letter ISO country code. “US” and “CA” are allowed. Required if bill_to_postal_code and bill_to_country are not provided. |
bill_to_phone | Optional | Billing phone. Numerical values, space, "-", "+", "x" allowed. Max 50 characters. |
bill_to_street_line_1 | Optional | Billing address line 1. Max 1000 characters. |
bill_to_street_line_2 | Optional | Billing address line 2. Max 1000 characters. |
bill_to_city | Optional | Billing city. Numerical values not allowed. Max 100 characters. |
bill_to_state | Conditional | Billing state. Two-letter state abbreviation. Required if bill_to_country is US or CA, but not needed if you are providing a ship-to address only. |
bill_to_postal_code | Conditional | Billing postal code. Only 4 or 5-digit numeral value. Include “0” in the beginning if it’s part of the postal code, like in MA, CT, and RI. Required if ship_to_postal_code and ship_to_country are not provided. |
bill_to_country | Conditional | Billing country. Two-letter ISO country code. If not provided, defaults to US. Required if ship_to_postal_code and ship_to_country are not provided. |
line_item_id | Optional | Unique ID of the line item. Defaults to ‘None’ when empty. Useful when one transaction has several line items. Up to 200 characters. |
product_external_id | Yes | Unique ID of a product stored in your order management or billing system. Must only contain alphanumeric characters, underscores, hyphens, and spaces. Max 200 characters. |
product_name | Optional | Name of the product. This field helps Kintsugi categorize the product accurately for tax, so it is worth filling in. Defaults to ‘None’ when left empty. Max 200 characters. |
product_description | Optional | Description of the product. General wording is fine. Defaults to ‘None’ when left empty. Max 1000 characters. |
amount | Yes | Final transaction amount after all discounts have been applied, but excluding tax. Format: General/Number. Must be a valid decimal number. Cannot be a negative amount or left blank. An empty string causes a validation error. |
tax_amount | Yes | Tax amount of the item. Format: General/Number. Must be a valid decimal number. Cannot be a negative amount or left blank. An empty string causes a validation error. Enter 0 if no tax was charged, rather than leaving it blank. |
quantity | Yes | Number of items sold. Should be > 0 and defaults to 1 if missing. Do not leave blank. An empty string causes a validation error. |
exempt | Yes | If the item is exempt from tax. Accepts valid boolean values (True/False, 1/0, T/F). An empty string causes a validation error. |
customer_exempt | Yes | If the customer is exempt from tax. Accepts valid boolean values (True/False, 1/0, T/F). Do not leave blank. An empty string causes a validation error. |
transaction_type | Yes | Type of the transaction. Valid values: SALE (default), FULL_CREDIT_NOTE, PARTIAL_CREDIT_NOTE, TAX_REFUND, ARCHIVE. If not provided, defaults to ‘SALE.’ |
operation | Yes | Operation to perform on the transaction. Valid values: IMPORT (default), UPDATE, ARCHIVE. If not provided, defaults to ‘IMPORT.’ Do not leave blank. An empty string causes a validation error. |
discount_amount | Optional | Total discount amount applied to the transaction. If provided, must be > 0 and less than the ‘amount.’ If not provided, defaults to ‘0.00’ or ‘None. Only applicable to transactions with a discount.’ |
Step 3: Upload Your CSV File
Save your completed file as a .CSV file
Log in to the Kintsugi App.
Go back to Data Sources tab from the left-side menu.
Go to the File Upload section and select the original source of the data from the dropdown.
If your source is not listed, select Other.
Upload your file by either clicking Choose File or by dragging and dropping the file to the dropbox.
What Happens Next
If your file has no errors
Kintsugi imports it for you. You do not need to confirm anything. When the import finishes, the upload area shows four counts:
Total Rows: how many rows Kintsugi read from your file
Validated: how many rows passed the checks
Persisted: how many transactions were saved to your account
Failed: how many rows were not saved
Address validation, product categorization, and tax calculation then run automatically on the imported data.
If some rows have errors
Kintsugi validates your entire file and opens Preview Mode, showing any errors (missing fields, bad formatting, wrong data types) before anything is committed. To review the full preview, scroll horizontally with Shift + scroll wheel and vertically with scrolling up and down.
If you spot any errors, go back to your CSV to fix them, then re-upload. If everything looks clean, click Upload to proceed.
Once the upload completes, you'll get a confirmation email at the address you're logged in with.
Kintsugi stops before importing and shows you what it found: Total Rows, Valid, and Errors, plus a table of just the rows that need attention. The problem cells are highlighted, and the specific reason is spelled out under each row, for example that a state code is required because the country is US, or that an amount cannot be empty.
From here you have two ways forward, and neither one requires a support ticket:
Option | What to do | When to choose it |
|---|---|---|
Fix everything, then upload again | Click Download error file. You get your own file back with an extra | Best in most cases. Nothing is imported until your data is right, so your totals stay clean. |
Import the good rows now | Click Upload N valid rows. Kintsugi imports the rows that passed and skips the rest. | Useful when you need most of the data in quickly. You can still download the error file afterward from Upload History and upload the corrected rows later. |
Tip: the error file is the fastest route. It tells you the row and the reason in one place, so you are not comparing screens side by side.
How to Confirm it Worked
Check the Persisted count in the upload area. That is how many transactions were saved.
Go to Transactions and filter by the source you selected to see the imported rows.
Come back to Upload History any time to re-check the status and counts, or to download the error file for a past upload. See Review the Uploaded Files in Kintsugi's Upload History.
Common Scenarios
Recording a refund
Add a row with transaction_type set to PARTIAL_CREDIT_NOTE for a partial refund or FULL_CREDIT_NOTE for a full one, and put the original sale's transaction_external_id in related_external_id.
Updating a transaction that is already in Kintsugi
Upload a row with the same transaction_external_id and set operation to UPDATE. This is how you change a status from PENDING to COMMITTED, for example. If you leave operation as IMPORT, Kintsugi treats the transaction as already present and skips the row, so nothing changes.
Removing a transaction
Uploaded transactions cannot be deleted outright. Upload a row with the same transaction_external_id and set operation to ARCHIVE. Kintsugi archives that record.
Uploading purchases instead of sales
Purchases follow the same upload area but need Transaction type switched to Purchases. See How to Upload Purchase Transactions in Kintsugi.
Troubleshooting
What you are seeing | Likely cause | How to fix it |
|---|---|---|
The file field is greyed out | No source selected yet | Choose your platform in Select Source first, then add your file |
The file is rejected before validation starts | Wrong file type or the file is too large | Save as CSV or XLSX and check the size against the limit shown in the upload area. Split a large historical import into smaller batches |
Status shows Validation failed | Kintsugi could not read the file, usually a formatting or encoding problem | Re-export from the Kintsugi template and save the CSV as UTF-8, then upload again |
Rows flagged on a boolean column such as exempt, customer_exempt, or marketplace | The cell was left blank | Enter TRUE/FALSE, 1/0, or T/F. Blank is not treated as FALSE |
Rows flagged on amount or tax_amount | Blank cell, text in a number column, or a negative value | Use a positive decimal number. Enter 0 rather than leaving the cell empty. Record refunds as credit note rows instead of negative amounts |
Rows flagged on an address column | Missing state or postal code for a US or Canadian address, or a postal code that lost its leading zero | Make sure at least one complete address is filled in. Format postal code columns as text in your spreadsheet so leading zeros survive |
Rows flagged on a date | A date that does not exist, such as 2026-02-30, or a cell that is not in the expected format | Check the calendar date, then apply the formula in Step 4 |
Persisted is lower than Total Rows | Some rows were skipped, or several line items were consolidated into one transaction | Click the Failed count in Upload History to download the error file. If Failed is 0, rows sharing a transaction ID were combined, which is expected |
An upload has been Validating or Importing for a long time | Large file, or the upload needs a closer look | Give it a few minutes, since the status refreshes on its own. If it has not moved, reach out through the chat bubble with the file name and upload date |
Things to Know
Uploaded transactions live in Kintsugi only. They are not written back to the platform the data came from.
Reuse the customer IDs Kintsugi already holds. Inventing a new ID for an existing customer creates a second customer record and splits their totals across both. Check the Customers tab before you upload.
Uploading the same file twice does not create duplicate transactions. Rows whose
transaction_external_idalready exists are skipped unless you setoperationto UPDATE.Several rows that share a
transaction_external_idare treated as line items of one transaction, so your transaction count can be lower than your row count without anything being wrong.Transactions in a period that has already been filed are locked and cannot be updated by upload. Reach out through the chat bubble if data for a filed period needs to change.
Every upload is its own entry in Upload History. A retry is not linked to the earlier attempt.
Upload History shows uploads made by anyone in your organization, not only your own.
If you later connect the same platform as a native integration, check for overlap on
customer_idandtransaction_external_idso the two sets of data reconcile cleanly.
FAQs
Q: Can I upload the same file again if I spotted a mistake?
A: Yes. Fix the flagged rows and upload again. Rows already in Kintsugi are skipped, and rows you set to UPDATE are applied to the existing transaction.
Q: My platform is not in the source list. Can I still upload?
A: Yes. Choose Other. Your data is processed exactly the same way.
Q: Does Kintsugi support currencies other than USD?
A: Yes. Any ISO 4217 currency code works in the currency column.
Q: How many transactions can I upload at once?
A: The upload area shows the current file size limit. If you are migrating a large history, split it into smaller batches by month or quarter. Smaller batches validate faster and make any errors much easier to isolate.
Q: Do I have to wait on the page while my file imports?
A: No. The status keeps updating in Upload History, so you can leave the page and check back.
Q: What happens to the rows I chose to skip?
A: They were never saved. Download the error file from Upload History, correct those rows, and upload them when you are ready.
Q: When will my uploaded data show up in my tax calculations?
A: Address validation, product categorization, and tax calculation start automatically after the import. If a filing deadline is close, upload with a few days to spare so the numbers are settled before you approve.
Need Help?
For further concerns, we're always here to help. If you can't find the answer you're looking for, just reach out to us using the chat in the bottom right corner of your screen.