Bulk Item Import from the CSV Template

Bulk Item Import creates catalog items from a CSV file that follows a fixed template. It's the right tool when you're preparing the item list yourself (rather than converting another system's export — for that, use the AI Import Wizard). It handles items only, up to 1,000 rows per file.

The wizard has three steps shown at the top of the page: Upload → Preview & Validate → Import. A Show me how link in the header replays a short guided tour of the screen any time.

1. Download and fill in the templateCopy Anchor Link

1. Open Tools → Utility from the sidebar and click the Bulk Item Import card (or go straight to /utility/import).
2. Click Download template — you get a CSV whose header row matches the item-create API exactly.
3. Fill it in. Required columns: itemId, productId, itemName, sellingPrice, costPrice. Optional columns include upc, description, season, type (STORE_ITEM or MODIFIER_ITEM), status (ACTIVE, INACTIVE, or ARCHIVED), and attribute references (departmentId, categoryId, subcategoryId, brandId, styleId, sizeId, colorId, taxId, discountId, imageGalleryId) — these must be numeric IDs of attributes that already exist in your catalog.
4. Save as UTF-8 CSV. Don't rename or add columns — unknown columns are rejected at upload.

2. Upload and review the validation previewCopy Anchor Link

1. Drop your CSV onto the upload box, or click it to browse.
2. The preview table shows every row with a Valid or Invalid badge and, for invalid rows, the exact reason (missing required value, non-numeric price, duplicate itemId, unknown status…).
3. Invalid rows are excluded from the import — either fix them in the file and re-upload, or continue with the valid rows only.
4. Click Import N valid rows to start (or Start over to pick a different file).

3. Import and handle failuresCopy Anchor Link

• A progress bar tracks the rows as they're created; each row's badge updates live to Created or Failed (with the server's message).
• Stay on the page — the dashboard warns you if you try to leave, because leaving cancels the rows that haven't been sent yet.
• When it finishes:
  • Retry N failed re-sends only the failed rows.
  • Download failures CSV gives you the failed and invalid rows in template format with an error column — fix and re-upload just that file.
  • View items in catalog jumps to Catalog → Items to see what you created.
  • Import another file resets the wizard.

Limits and gotchasCopy Anchor Link

• CSV only (the AI wizard also accepts XLSX/TSV/JSON).
• 1,000 rows per file — split larger files.
• This wizard always creates items; it does not update existing ones. A row whose itemId already exists will fail — use the AI Import Wizard with "Update it" if you need bulk updates.