📤 File Upload Overview

Need to get your sales data into Kintsugi but don’t have an existing integration? No problem! You can easily upload your sales transactions using a CSV file.

Before uploading, please ensure your CSV file follows the required format. This guide will walk you through the simple steps to prepare and upload your file successfully.

📋 Step 1: Get the Manual Upload Template

1. Open the Kintsugi App.

2. Navigate to Data Sources.

3. Click on File Upload Template.

4. Download the template from the next screen.

This template is crucial as it ensures your data is the correct format for Kintsugi.

💡 Step 2: Prepare Your CSV File

✅ Required Fields

1. The template has required fields marked in red.

2. Make sure your CSV includes all of these. Upload errors may occur if any are missing.

📅 Date Formatting Tip

To ensure the date field is in the correct format, use the following Excel formula:

=TEXT(D27,"YYYY-mm-dd") & "T" & TEXT(D27,"hh:mm:ss")

When handling date and time data, you can specify a time zone by including a full ISO-8601 datetime string with an offset. If no offset is provided, the system assumes the time is in Coordinated Universal Time (UTC).
​

For example, 2025-02-28T23:00:00-05:00 is stored as:

• shop_date: 2025-02-28 (Local transaction date)

• date: 2025-03-01 04:00:00 (UTC conversion)

• shop_tz: -05:00 (Local offset)

Transactions are filed based on the local date when they occurred, ensuring accurate reporting.
​
For detailed explanations of each column and best practices, refer to this additional resource.

🗺️ Data Mapping Reference

1. Use the table below to match your data to the Kintsugi template columns:

   Field Name	Required (Yes/No/Conditional)	Additional Description
   related_external_id	Conditional	Required when transaction_type is FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE; optional otherwise. Must contain only alphanumeric characters, underscores, and hyphens.
   transaction_external_id	Yes	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	No	Description of the transaction. Max 1000 characters.
   customer_id	Yes	Unique ID for the customer. Must only contain alphanumeric characters, underscores, and hyphens. Max 100 characters.
   customer_name	No	Name of the customer. Max 200 characters.
   customer_email	No	Email of the customer. Must be a valid email format. Max 200 characters.
   marketplace	Yes	If a transaction is from a marketplace facilitator (True/False). Default to false if missing; empty string causes validation error.
   ship_to_phone	No	Shipping address phone. Allows numerical values, space, "-", "+", "x." Max 50 characters.
   ship_to_street_line_1	No	Shipping address line 1. Max 1000 characters.
   ship_to_street_line_2	No	Shipping address line 2. Max 1000 characters.
   ship_to_city	No	Shipping city. Numerical values not allowed. Max 1000 characters.
   ship_to_state	Conditional	Shipping state. 2-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. Required if bill_to_postal_code and bill_to_country are empty.
   ship_to_country	Conditional	Shipping country. “US” and “CA” are allowed. Required if bill_to_postal_code and bill_to_country are not provided.
   bill_to_phone	No	Billing phone. Numerical values, space, "-", "+", "x" allowed.  Max 50 characters.
   bill_to_street_line_1	No	Billing address line 1. Max 1000 characters.
   bill_to_street_line_2	No	Billing address line 2. Max 1000 characters.
   bill_to_city	No	Billing city. Numerical values not allowed. Max 100 characters.
   bill_to_state	Conditional	Billing state. 2-letter state abbreviation. Required if bill_to_country is US or CA,  but not when you only provide the ship_to address.
   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. If not provided, defaults to US. Required if ship_to_postal_code and ship_to_country are not provided.
   line_item_id	No	Unique ID of the transaction item. Defaults to ‘None’ when empty. Max 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	No	Name of the product. This field helps categorize the product accurately. Defaults to ‘None’ when left empty. Max 200 characters.
   product_description	No	Description of the product. 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.
   quantity	Yes	Number of items sold. Should be > 0 and defaults to 1 if missing. 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). 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.’ FULL_CREDIT_NOTE and PARTIAL_CREDIT_NOTE require related_external_id. An empty string causes a validation error.
   operation	Yes	Operation to perform on the transaction. Valid values: IMPORT (default), UPDATE, ARCHIVE. If not provided, defaults to ‘IMPORT.’ An empty string causes a validation error.
   discount_amount	No	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

1. Save your completed file as a .CSV file

2. Log in to the Kintsugi App.

3. Go to the manual upload option.

4. Select the original source of the data from the dropdown.

   • If your source is not listed, select Other.

🧾 Special Case: Refunds

For refunded or partially refunded transactions:

• Include the related_external_id.

• Set the transaction_type to Partial_Credit_Note.

🧾 Special Case: Deleting a Manual Upload

You can not currently delete a manual upload, however you can archive specific transactions by using the ID and adding archive in the operation field. See the additional resource mentioned above:

🚀 Step 4: Complete the Upload Process

1. Click Choose File to select your CSV.

2. Kintsugi will run validation checks on sample data.

   1. If errors are found, you’ll see them in Preview Mode and must fix them before uploading.

   2. If no errors are found, you can proceed with the upload.

3. Once uploaded, a confirmation email will be sent to the logged-in user’s email.

   1. Double-check that all required fields are filled—missing any mandatory fields may result in upload errors.

   2. For refunded or partially refunded transactions, be sure to include the related_external_id and set the transaction_type as Partial_Credit_Note

   3. If you need further assistance, please reach out to Kintsugi Customer Success using the chatbot in the bottom right corner of the platform.

🆘 Need Help?

For further concerns, we're always here to help. If you can't find the answer you're looking for, please reach out to us using the chat bubble in the bottom right corner.