Skip to main content

Importing Products from CSV (V2)

Learn how to import and update products using CSV files in Catalog Machine.

Faster than reading? Try the AI assistants:

Note: This article covers the latest Catalog Machine version 2. For help with the previous version, see this article.

Overview

Catalog Machine's CSV import allows you to import new products and variants from spreadsheets, update existing product information in bulk, add products to categories and collections, import product images from various sources, and extend products with custom fields.

Learn more about managing products.

Quick Start Guide

Common Scenarios

  1. Want AI to handle a tricky CSV? Upload it to AI Concierge — it auto-detects categories, suggests field mapping, and handles unusual formats.

  2. Import from Excel: File → Save As → CSV (UTF-8) → Upload to Import → CSV in Catalog Machine

  3. Import from Google Sheets: File → Download → CSV → Upload to Import → CSV

  4. Update Existing Products: Export current products as CSV → Edit → Save as CSV → Re-import

Watch this short 3-minute video for an overview of importing products from CSV (Excel / Google):

Before You Start

Requirements

  • CSV file with product data

  • First row must have field names; column names should match your category fields (new fields will be suggested during import)

  • Name field is required for new products

  • Use Code field to match and update existing products

  • Other fields are optional

Important: Code acts as your unique product identifier/key. Best practice: use your existing product IDs, SKUs, or other stable identifiers. If Code matches an existing product, it will update that product. If no match found, creates new product. If not provided, system will auto-generate (not recommended for future updates).

Data Preparation Tips

  • Review your product information structure

  • Prepare high-quality product images

  • Plan your category and collection structure

Step-by-Step Import Process

1. Prepare Your File

  • Use CSV format with UTF-8 encoding

  • Include header row

  • If Code field is present and matching product is found, it will be updated, otherwise inserted

  • Category is required for new products

2. Start Import

Navigate to Import → CSV: Upload file or paste content, select default category (optional), choose target collection (optional). The target collection option adds the imported products to that collection without removing them from any of their existing collections.

3. Review Analysis and Configure Data Types

System checks for: data structure, new categories/fields, missing required fields, potential issues. You can confirm new fields, set data types, map missing fields, configure variant options.

4. Preview and Import

Review sample records, verify mappings, start import, monitor progress.

Technical Reference

CSV File Format Requirements

  • UTF-8 encoded CSV file (supporting international symbols)

  • First row contains field headers

  • Each row represents a product or variant

  • Values separated by commas

  • Text containing commas should be enclosed in quotes

Tip: Export template with all fields as a starting point, or use product export to get CSV file for existing products.

Working with Spreadsheet Programs

Microsoft Excel: Edit data → File → Save As → "CSV (Comma delimited) (*.csv)". For international characters, save as "CSV UTF-8 (Comma delimited) (*.csv)".

Google Sheets: Edit data → File → Download → Comma-separated values (.csv). Automatically downloads in UTF-8 format.

Read more about Asian characters import and use.

Header Row Fields

Note: First row contains field headers that correspond to your category fields. Common reserved fields: Code, Name, Price, Description, Category.

Standard fields: Code (optional, unique product identifier; auto-generated if missing); Name (required for new products); Category (must match existing or will create new); Rank (numeric sorting); Showcase (1 = visible in Showroom, 0 = hidden).

Collections

Note: A Collections column in your CSV will replace a product's existing collections (the product ends up only in the collections listed in its row). To add products to a collection without removing the others, leave out the Collections column and use the target collection option in the import setup instead.

Single column: "Best Sellers, New Arrivals/Dresses". Multiple columns: Collections 1, Collections 2. Use forward slash (/) for hierarchy: Cars/Ford/Mustang.

Working with Images

1. Local Images — Upload to Image Manager first, then reference in CSV using relative paths (e.g., Products/blue-shirt.jpg).

2. Web URLs — Direct links to public images: https://example.com/image.jpg. JPG, PNG, GIF, WEBP. Max 10MB.

3. File Sharing Services: Google Drive (convert to direct download URL: https://drive.google.com/uc?export=download&id=FILEID), Dropbox (replace ?dl=0 with ?dl=1).

Note: Image field names in CSV must exactly match the category's image field names.

In your CSV, image fields can contain: relative path, absolute URL, or data URL (base64 encoded). Use Catalog Machine export or tools like https://dopiaza.org/tools/datauri to generate data URLs.

Import worked but 0 images loaded? This is recoverable without redoing the import. Almost always the image column holds bare file names copied from a supplier spreadsheet (BD652701_v1_1.jpg) rather than a path or a URL, so there was nothing for the importer to fetch. Nothing is wrong with your file.

The fix is to give those names something to match against. Upload the actual image files under Images, putting them where the CSV says they are: a column reading BD652701_v1_1.jpg means the root of the image library, and Products/BD652701_v1_1.jpg means a Products folder. Then re-import the same CSV, unchanged. The importer matches each name against your library and links the file that is already there.

Two things break the match: names are case sensitive, so IMG_001.JPG will not match img_001.jpg; and the extension is part of the name, so a column reading BD652701_v1_1 with no .jpg will not match. Re-importing is safe here, because matching on Code updates your existing products rather than duplicating them. If you only want to fix the pictures, a two-column CSV of Code plus the image field is the cleanest re-import.

Multiple images per product: create multiple image fields in category, name them differently (e.g., Image1, Image2), reference in CSV by field name.

Special Content Types

Rich Text Fields: Support basic HTML formatting (CSS not supported). Example: <div>Product description with <b>bold</b> and <i>italic</i> text</div>

Variant Fields: Use same product Code to link variants to the parent product, one row per variant. Prefix each variant column with Variant: — keeping the space after the colon. Example:

Code,Name,Variant: Size,Variant: Color,Variant: Price 
SHIRT-1,"Blue Shirt","M","Blue",28.99 
SHIRT-1,"Blue Shirt","L","Red",29.99

Important: write Variant: Size, not Variant:Size. Without the space the column is read as an ordinary product field, the extra rows merge into the parent product, and the variants are dropped — while the import still reports success. The safest way to get the header exactly right is to export your products to CSV first and reuse its header row.

Built-in variant fields — these are the only ones: Variant: Image, Variant: SKU, Variant: Price, Variant: Description, Variant: External Id, Variant: Barcode, Variant: Quantity. There is one image per variant, so there is no Variant: ImageFront / Variant: ImageBack — for a second picture, add another Image field to the product's category (e.g. "Image 2") and fill it at product level.

Variant options are anything else you name — Variant: Size, Variant: Color, Variant: Design — and each becomes a selectable option on the product. Free accounts are limited to 5 variants per product; the import reports any product it had to truncate.

Tips for Successful Import

  1. Start with a template (export existing products or use sample CSV)

  2. Verify encoding (UTF-8)

  3. Test with small sample first

  4. Or skip the prep — upload to AI Concierge and let it handle category detection and field mapping

Common Issues and Solutions

  1. Encoding Problems: Save as UTF-8 CSV, or copy/paste directly into import

  2. Image Import Failures: Check URL accessibility, file size limits, format support. If the report says 0 of N images, the column most likely holds bare file names rather than paths or URLs - see Working with Images above for the fix

  3. Missing Data: Check required fields, category mismatches, invalid collection paths

  4. Variants Disappeared: the Variant: prefix was written without the space after the colon, so the column imported as a plain product field

Need Help?

Use AI Help (chat icon) for instant answers, or chat with our support team for: file preparation, image importing, error resolution, custom requirements.

Did this answer your question?