CSV Import

Importing Data via CSV

Cartly's import system allows you to bulk-add or update products using CSV files. The import process is powered by Temporal workflows for reliability and progress tracking.

Preparing Your CSV File

Your CSV file should follow these guidelines:

• Use UTF-8 encoding to support international characters
• Include a header row with column names
• Use commas as delimiters (not semicolons or tabs)
• Wrap values containing commas in double quotes
• One row per variant (group rows by product title for multi-variant products)

Required Columns

At minimum, your CSV needs:

• title — The product name. This is the grouping key for variants.
• price — The selling price in decimal format (e.g., 29.99)

All other columns are optional but recommended for complete product data.

Upload Process

1. Navigate to Products → Import
2. Select your CSV file (drag and drop or click to browse)
3. Cartly parses the file and shows a preview of the first 5 rows
4. Map each CSV column to a Cartly product field. If your column names match the expected names, mapping is automatic.
5. Review the mapping and click Start Import

Import Progress

Once started, the import runs as a background Temporal workflow. You can:

• View real-time progress (processed / total rows)
• See counts of created, updated, and failed rows
• Navigate away and come back — the import continues in the background

Error Handling

Rows that fail validation are skipped and logged with specific error messages. Common errors include:

• Missing required fields (title, price)
• Invalid price format
• Duplicate SKUs within the same import
• Image URL download failures

After the import completes, download a CSV of failed rows, fix the issues, and re-import just those rows.

Update vs. Create

If a product with the same title (or handle, if specified) already exists, the import updates it instead of creating a duplicate. This allows you to use CSV imports for bulk price updates, inventory adjustments, or adding new fields to existing products.

Performance

Imports process rows in configurable batches (default: 100). A typical 5,000-row file completes in about one minute. The Temporal workflow ensures that even if the server restarts during processing, the import resumes from the last completed batch.