Bulk Import & Export Products (CSV)

Adding products one by one is fine for a small menu, but it gets slow when you have a real catalog. Bulk import lets you build every product in a spreadsheet (Excel, Google Sheets, or Numbers), save it as a CSV file, and upload it once so all the rows become live products in seconds. Export does the reverse: it downloads your current catalog as a CSV you can back up, edit in bulk, or move to another store.

This is the right tool when you are launching a new store with a long product list, migrating from another platform, or doing a seasonal price update across many items. For one or two quick edits, the normal Create new and Edit buttons are faster. The golden rule: categories must exist before you import, because every product row points at a category by its ID, and import will not create categories for you.

Your import file must have a header row (the first row) with these nine columns, in any order but spelled exactly: category_id, badge, product_image, product_name, product_short_description, product_description, regular_price, sales_price, product_status. The system trims spaces, lowercases the header, and strips the hidden Excel BOM marker automatically, so capitalization in the header is forgiven, but the words themselves must match. A missing or misspelled column stops the whole import before any product is created.

category_id is the most important field: it is the short code of an existing category in your store (for example 68b8a837ea78f), not the category's name. You get this code by opening your store's Categories section first; every product row must use a code that already exists, or that row is skipped with an error. Put each product under the category you want it to appear in on the storefront.

product_name is the display title, product_short_description is the one-line teaser shown on cards, and product_description is the full body text. badge is the small ribbon on the product (for example Best Seller or Save 25%). Note an important quirk: in import all nine columns are treated as required — even badge, product_short_description, and product_description. If you leave any of them blank, that row is rejected. If you truly do not want a badge, put a placeholder like a single dash - rather than leaving the cell empty.

regular_price is the list price and sales_price is the discounted price; both are plain numbers (use 49.99, not $49.99 or 49,99). product_image is the image: paste the same image path or URL the store editor uses, or copy it from an exported file. product_status accepts exactly two values: instock or outstock — any other word will display incorrectly, so do not write "In Stock" or "Available" here. The product's own unique ID is generated for you on import, so there is no product_id column to fill in.

Exporting first is the safest way to learn the format, because it gives you a real CSV that already matches your store. Open your store in the editor, go to the Products section, and look at the toolbar in the top-right of the page header. Click the Export button (the one with the download icon).

Your browser immediately downloads a file named after your store, like mystore_products.csv. Open it in Excel or Google Sheets. You will see the file contains fourteen columns — the nine import columns plus five extra ones the export adds: card_id, product_id, status, created_at, and updated_at. These extras are for reference and backup; they record which store the product belongs to and when it was created.

Heads-up before you re-import an exported file: the import expects exactly nine columns per row, so an unedited export with fourteen columns will be rejected with a "column mismatch" message. If your goal is to edit and re-import, delete the five extra columns (card_id, product_id, status, created_at, updated_at) and keep only the nine import columns. Treat export as a backup-and-template tool, not a one-click round-trip.

First make sure your categories already exist. Open the Categories section of your store and create every category you reference, then copy each category's ID into the matching rows of your spreadsheet's category_id column. Skipping this step is the number-one cause of failed imports, because a product pointing at a category that does not exist is rejected row by row.

When your spreadsheet is ready, save it as CSV (in Excel: File → Save As → CSV UTF-8; in Google Sheets: File → Download → Comma-separated values). The importer auto-detects whether your file uses commas or tabs as separators, so both work, but a real .csv extension is required — the upload only accepts CSV files, not .xlsx workbooks.

Back on the Products page, click the Import button in the toolbar (the one with the package icon). A small Import dialog opens with a single file field. If you are unsure of the layout, click the Sample CSV button at the bottom of the dialog first to download a template you can fill in.

Click the File field, choose your .csv file, then click the blue Import button. The page uploads the file and processes every row in turn. On success you see a green Product import successful message, the dialog closes, and the products table refreshes to show the new items right away — no page reload needed.

Important edge case: import is not all-or-nothing. The system creates each valid row as it goes and only collects the bad rows to report at the end. So if rows 2–5 are perfect but row 6 has a missing field, rows 2–5 are already saved while row 6 is skipped and listed in a red error message. If an import partially fails, fix only the reported rows in your file, delete the rows that already imported, and re-upload — otherwise you will create duplicates.

"CSV is missing required columns: …" — your header row is missing or misspells one of the nine columns. Open the file and check the first row character by character against the required list; watch for plurals (prices instead of price), extra spaces inside a header, or a column you deleted. Fix the header and re-upload. This error stops the whole import, so nothing was created.

"Row N: Column mismatch." — that row has more or fewer cells than the header. The usual culprit is a comma inside a description or price that splits the cell, or leftover extra columns from an exported file. Wrap any text that contains a comma in double quotes ("Sweet, smoky sauce"), or re-save the file from your spreadsheet which quotes such fields automatically. If you started from an export, delete the five extra columns so each row has exactly nine.

"Row N: Missing value for 'field'." — a required cell in that row is empty. Remember every one of the nine columns must be filled, including badge, product_short_description, and product_description. Fill the blank cell (use a dash - if you have nothing meaningful for a badge), then re-import only the corrected rows.

"Row N: Category ID '…' does not exist." — the category_id in that row does not match any category in your store. Re-open the Categories section, confirm the category exists, and copy its exact ID (these codes are case-sensitive and have no spaces). A common mistake is typing the category's name instead of its ID, or importing into the wrong store. Create the missing category first, then re-import.

"Something went wrong!" (a generic failure) — this usually means the upload itself was rejected before processing: the file was not a real CSV (for example an .xlsx renamed to .csv), or it was empty. Re-save genuinely as CSV from your spreadsheet and try again. If prices show up wrong after import, check you used a dot for decimals (9.50) and removed any currency symbols or thousands separators.

Export first, then build from it. The fastest way to a clean import file is to add one product manually in the editor, export, and use that real row as your template. You will see exactly how product_image paths and category_id codes are formatted, so you are copying a known-good shape instead of guessing.

Test with a few rows before the big batch. Import a 3-row file first. If those land correctly, you have proven your headers, category IDs, and price format all work, and you can confidently import the full hundreds-of-rows file. This turns a frustrating debugging session into a 30-second check.

Keep a master spreadsheet. Maintain one source-of-truth sheet for your catalog and export from the store only to back it up. Doing seasonal price changes, badge swaps, or a sale becomes a quick find-and-replace in your master file, followed by a fresh import into a clean store rather than editing live rows one by one.

Save as UTF-8. If your product names or descriptions are in Arabic or contain accented letters, always pick the CSV UTF-8 option when saving. A plain or Windows-encoded CSV can turn Arabic text into garbled characters after import. The importer already strips Excel's hidden BOM marker, so UTF-8 is the safe choice.

Remember what import cannot set. Bulk import only handles the nine core fields. Stock count, product variants (sizes/colors), and video URLs are not imported — they must be added in the editor afterward. Plan for this: import to build the catalog skeleton fast, then open the few products that need variants or stock limits and finish them by hand.

Can I upload an Excel (.xlsx) file directly? No. The importer only accepts CSV files. Open your workbook in Excel or Google Sheets and use Save As / Download to convert it to .csv first. Renaming an .xlsx to .csv does not work and will be rejected.

Will importing delete or overwrite my existing products? No. Import only adds new products; it never updates or removes what is already in your store. Each imported row becomes a brand-new product with its own freshly generated ID. If you import the same file twice, you will get duplicate products, so delete an existing set before re-importing it.

Why was my exported file rejected when I tried to import it again? Because export adds five extra columns (card_id, product_id, status, created_at, updated_at) for a total of fourteen, while import expects exactly the nine core columns. Delete the five extras before re-importing. This is the most common surprise when round-tripping a file.

Where do I find a category's ID for the category_id column? Open the Categories section of your store editor. Each category has a short code (something like 68b8a837ea78f) that you use in the CSV — not the visible name. Copy it exactly, including its mix of letters and numbers, since these codes are case-sensitive.

What values are allowed for product_status? Exactly two: instock and outstock. These are the stored codes the storefront understands. Do not write friendly text like "In Stock" or "Available" in the CSV — that is only the label you see in the editor dropdown, not the value the import expects.

Is there a limit on how many products I can import at once? There is no fixed row cap, but very large files take longer and a single bad row near the end still leaves all earlier valid rows saved. For big catalogs, split into batches of a few hundred rows. That keeps uploads fast, makes any error easy to locate, and limits how much you would need to clean up if something goes wrong.