CSV templates
The column rules for the product import and the customer import, plus the serial number upload.
This page lists the columns each CSV import expects and the rules the server checks. Both main imports have a template button. Start from the template, then add your own rows.
Before you start#
- The product import needs Available on Startup and above and the permission to import products.
- The customer import works on every plan. You need the permission to create customers.
- Both imports need a larger screen. On a phone the page tells you to use a computer.
- Save the file as CSV. Excel files are not read.
Product import#
You open it from Products, then Bulk add. The full steps are in Bulk import (CSV). Click Download CSV template to get a file with the right headers and four example rows.
The 16 columns#
The file must have these 16 columns, in this order. Letter case does not matter. Extra columns after the sixteenth are ignored.
| Column | Rule |
|---|---|
| Product Name | Required. At least 2 characters. Rows with the same name (any letter case) become one product with variants. |
| Variant Name | Required on every row of a product that has more than one row. Must be unique within that product. |
| SKU | Optional. If you fill it in, it must be exactly 6 digits. If you leave it blank, one is made for you. |
| Product Type | standard or serialized. Other types cannot be imported. |
| Unit | A unit the app knows. See the unit list below. |
| Unit Value | A number greater than 0. Decimals are fine, for example 0.5. |
| Price | Required. A plain number of 0 or more, for example 1450.00. A price of 0 makes the product an open price product. |
| Cost | Optional. A plain number of 0 or more. |
| MSRP | Optional. A plain number of 0 or more. |
| Description | Optional free text. |
| Track Inventory | Yes or no. Blank means no. A serialized product always tracks inventory. |
| Batch Tracking | Yes or no. Needs Track Inventory. |
| Expiry Tracking | Yes or no. Needs Batch Tracking. |
| Barcode | Yes or no. If Barcode or QR Code is yes, the product gets a 13 digit code. Each variant gets its own. |
| QR Code | Yes or no. Works the same way as Barcode. |
| Global Identifier Value | Optional. Exactly 13 digits. It is stored as the barcode. If Barcode or QR Code is yes and this is blank, a 13 digit code is made for you. |
For the yes or no columns, true, yes and 1 mean yes. false, no, 0 and a blank cell mean no. The template uses true and false. Any other value is an error.
Money columns are plain amounts in your business's currency. Do not add a currency sign or thousands separators.
Units#
These values are accepted, in any letter case: mm, cm, m, in, ft, sf, mg, g, kg, ml, l, piece, pcs, pack, qty, card, lbs, box. Full words also work, for example kilogram, liters, pieces, feet or boxes.
Rows that make one product#
All rows of one product must agree on Product Type, Unit, Unit Value, Track Inventory, Batch Tracking and Expiry Tracking. If a later row disagrees, the error is shown on that later row and names the first row. Description and the code columns are taken from the first row.
Limits and checks#
- Up to 500 product rows per file. The page says files can be up to 10 MB.
- Product names, SKUs and barcodes must be unique in the file and in your existing catalogue.
- The import only creates new products. It cannot change a product you already have.
Customer import#
You open it from Customers, then Import CSV. The full steps are in Import and export. Click Download template to get a file with the headers and one example row.
The columns#
Columns are matched by name, so the order does not matter and you can leave columns out. Letter case does not matter, and a space counts as an underscore, so First Name works for first_name. Columns the import does not know are ignored.
| Column | Rule |
|---|---|
| first_name | Required. The file must have this column. |
| last_name | Optional. |
The file must have an email or a phone column. Each row needs one of the two. The email must look like a real address. | |
| phone | See email. |
| street_address, city, state, zip_code, country | Optional address fields. |
| birthday | Optional. Written as YYYY-MM-DD, for example 1990-04-21. Must be a real date, not in the future. |
| tags | Optional. Put several tags in one cell, separated by semicolons, for example VIP;wholesale. Up to 25 tags, each up to 40 characters. |
| marketing_opt_in | Optional yes or no. Blank means no. |
| notes | Optional. Up to 5,000 characters. |
| is_active | Optional yes or no. Blank means active. |
Emails and phone numbers must be unique across your business, ignoring letter case. The export uses the same columns, so you can edit an exported file and import it again.
Limits#
- Up to 2,000 rows per file.
- Up to 8 MB per file. The page refuses a larger file. Split it and import in batches.
Serial number upload#
When you add stock for a serialized product, the Serial numbers intake section has a Bulk CSV import button. The file needs only one column of serial numbers. If the first row is a header such as serial, serial_number or sn, that column is used. Otherwise the first column is used. The app checks each number and shows Import valid serials only, which skips numbers that are already in stock or already added. There is no template for this file.
Behind the scenes#
The two main imports fail in different ways.
- Products: all or nothing. The server checks the whole file first and lists every problem at once. If there is any error, it saves nothing. When the file passes, you see a preview and can untick products before you click Import catalog.
- Customers: the clean rows go in. Validate file checks the file without saving. The button then changes to Import valid rows, which saves the good rows and skips the rest. A few problems only show at this step, so read the summary after the import too.
Every error names the row in your spreadsheet. The header is row 1, so the first data row is row 2. A product error looks like this:
Row 12 | Product "Red rice 5kg" (Column: SKU): SKU must be exactly 6 numeric digits (got '12345')
The product page has a Copy log button so you can keep the list while you fix the file.
Watch out#
Troubleshooting#
| Symptom | Cause | Fix |
|---|---|---|
| "Invalid CSV headers. Expected 16 columns" | The product file has fewer than 16 columns, or they are in a different order. | Start from Download CSV template and keep its header row as it is. |
| A group error on a later row that names an earlier row | Two rows of the same product disagree on type, unit, unit value or tracking. | Make the rows match, or give them different product names. |
| "Product name already exists in the system" | The product is already in your catalogue. | The import cannot update it. Change it on the product page, or remove the row. |
| "the file is missing the "first_name" column" | The customer file has no first name column. | Add the column, or rename yours to first_name. |
| Some customer rows were skipped | Those rows failed a check. | Open the summary, fix those rows only, and import them again. |