catalog-import-export

# Catalog Import / Export

## Overview

Bulk importing and exporting products is a core catalog management task — whether you're onboarding a new store from a supplier spreadsheet, doing mass price updates, or feeding products to Google Merchant Center. Every major platform has native import/export tools that handle this without custom code. Use them first; only build a custom pipeline if your volume, format, or validation requirements exceed what the platform offers.

## When to Use This Skill

- When onboarding a new merchant whose catalog lives in a spreadsheet or ERP system
- When syncing product data from a supplier or PIM on a scheduled basis
- When merchants need to do mass price or inventory updates without coding
- When building a product feed export for Google Merchant Center, Amazon, or comparison shopping engines

## Core Instructions

### Step 1: Determine the platform and choose the right import tool

| Platform | Recommended Tool | Why |
|----------|-----------------|-----|
| **Shopify** | Matrixify (Bulk Product Import Export) | Handles complex catalogs with metafields, variants, multiple images, and collections; supports scheduled sync and error reports |
| **Shopify (simple)** | Shopify's built-in CSV import | Free, sufficient for basic catalogs under a few hundred products with standard fields only |
| **WooCommerce** | WP All Import Pro | Most powerful WooCommerce import tool; supports CSV/XML, field mapping, scheduled imports, and conditional logic |
| **WooCommerce (built-in)** | WooCommerce Product CSV Importer | Ships with WooCommerce; handles products, variations, and images for simple use cases |
| **BigCommerce** | Built-in bulk import / Feedonomics | BigCommerce's native import handles most needs; Feedonomics for multi-channel feed management |
| **Custom / Headless** | Build a custom pipeline | Only if your platform has no native tools or your validation/transformation requirements are too complex |

---

### Step 2: Prepare your import file

Regardless of platform, product import files follow a similar structure. Use the platform's sample CSV as your template:

- **Shopify**: Download the sample CSV from **Products → Import → Download sample CSV**
- **WooCommerce**: Download from **Products → Import → Download sample CSV**
- **BigCommerce**: Download from **Products → Import & Export → Download template**

Key fields almost every platform requires:

| Field | Notes |
|-------|-------|
| Handle / Slug | URL-safe unique identifier (e.g., `blue-cotton-tshirt`) |
| Title | Product name |
| Price | Decimal, e.g., `29.99` |
| SKU | Unique per variant |
| Inventory Quantity | Integer |
| Images | Comma-separated URLs or upload separately |
| Variant options | Size, Color, etc. |

**Important formatting rules:**
- Save CSV files as UTF-8 encoding (in Excel: Save As → CSV UTF-8)
- Use the exact column headers from the platform's sample template
- Dates in ISO format: `2026-03-12`
- Boolean values: `true` / `false` (not `yes`/`no` or `1`/`0` unless the platform specifies)

---

### Step 3: Platform-specific setup

---

#### Shopify

**Option A: Built-in CSV import (simple catalogs)**

1. Go to **Admin → Products → Import**
2. Download the sample CSV to use as a template
3. Prepare your file following Shopify's column format exactly
4. Upload the CSV and click **Import products**
5. Shopify shows a summary of what will be created/updated; review before confirming

Limitations: No support for metafields, custom collections, or complex variant logic in the built-in importer.

**Option B: Matrixify (recommended for complex catalogs)**

1. Install **Matrixify** from the Shopify App Store
2. In Matrixify, click **Export** to download your current catalog as a reference spreadsheet
3. Use the exported format to prepare your import file — it includes all supported columns with examples
4. Upload your file and click **Import**
5. Matrixify shows a row-by-row error report — download it and fix errors before re-running
6. For scheduled sync: go to **Matrixify → Schedules → Add schedule**, set frequency (hourly, daily, etc.), and point to a Google Sheets URL or FTP path

**Exporting for Google Merchant Center:**
1. In Matrixify, go to **Export**
2. Choose **Google Shopping** as the export template
3. Download the feed XML and upload to Google Merchant Center, or use Matrixify's direct Google Sheets sync

---

#### WooCommerce

**Option A: Built-in product importer**

1. Go to **WooCommerce → Products → Import**
2. Upload your CSV file
3. On the column mapping screen, match your CSV columns to WooCommerce fields
4. Click **Run the importer** — WooCommerce shows a progress bar and summary

**Option B: WP All Import Pro (recommended for advanced needs)**

1. Install **WP All Import Pro** + the **WooCommerce Add-On**
2. Go to **All Import → New Import**
3. Upload your CSV or XML file, or enter a URL for scheduled imports
4. Use the drag-and-drop field mapper to connect your file's columns to WooCommerce product fields
5. Set up **Scheduling**: All Import → Manage Imports → Edit → Run automatically every X hours
6. Review the import log at **All Import → History** — errors are listed with row numbers

**For Google Merchant Center feed export:**
- Install **Product Feed Pro for WooCommerce** (free)
- Go to **Product Feed Pro → Manage Feeds → Add Feed**
- Select Google Shopping as the template
- Configure and publish the feed URL directly to Google Merchant Center

---

#### BigCommerce

**Built-in bulk import:**

1. Go to **Products → Import & Export → Import Products**
2. Download the CSV template
3. Prepare your file and upload
4. BigCommerce validates the file and shows a preview before committing
5. For images: host images at accessible URLs and include them in the `Product Image URL` column

**Google Shopping feed:**
- Go to **Channel Manager → Google Shopping**
- BigCommerce has native Google Shopping integration — connect your Google Merchant Center account and BigCommerce syncs the catalog automatically

**For advanced multi-channel feeds:** Install **Feedonomics** or **GoDataFeed** from the BigCommerce App Marketplace for Amazon, eBay, and comparison engine feeds.

---

#### Custom / Headless

For headless storefronts, build a pipeline that validates, transforms, and upserts products:

```typescript
// lib/catalogImport.ts
import { z } from 'zod';
import { parse } from 'csv-parse';
import { createReadStream } from 'fs';

// Define and validate the import schema
const productRowSchema = z.object({
  handle: z.string().min(1).regex(/^[a-z0-9-]+$/, 'Handle must be lowercase alphanumeric with hyphens'),
  title: z.string().min(1).max(255),
  price: z.coerce.number().positive(),
  sku: z.string().min(1),
  inventory_quantity: z.coerce.number().int().min(0).default(0),
  image_url: z.string().url().optional(),
});

// Stream-parse large CSV files without loading into memory
export async function* parseCatalogCsv(filePath: string) {
  const parser = createReadStream(filePath).pipe(
    parse({ columns: true, skip_empty_lines: true, trim: true })
  );
  let rowIndex = 2;
  for await (const rawRow of parser) {
    const result = productRowSchema.safeParse(rawRow);
    yield result.success
      ? { row: rowIndex, data: result.data, errors: null }
      : { row: rowIndex, data: null, errors: result.error.issues.map(i => ({ field: i.path.join('.'), message: i.message })) };
    rowIndex++;
  }
}

// Process as an async job with upsert logic (idempotent, safe to re-run)
export async function runCatalogImport(filePath: string) {
  let processed = 0;
  const errors: { row: number; errors: { field: string; message: string }[] }[] = [];

  for await (const { row, data, errors: rowErrors } of parseCatalogCsv(filePath)) {
    if (rowErrors) { errors.push({ row, errors: rowErrors }); continue; }
    // Upsert by handle — re-running the same file won't create duplicates
    await db.products.upsert({ where: { handle: data!.handle }, create: data!, update: data! });
    processed++;
  }

  return { processed, errorCount: errors.length, errors: errors.slice(0, 50) };
}
```

For Google Merchant Center XML export:

```typescript
import { create } from 'xmlbuilder2';

export async function exportGoogleFeed(products: Product[]) {
  const root = create({ version: '1.0', encoding: 'UTF-8' })
    .ele('rss', { version: '2.0', 'xmlns:g': 'http://base.google.com/ns/1.0' })
    .ele('channel');

  for (const product of products) {
    const item = root.ele('item');
    item.ele('g:id').txt(product.sku);
    item.ele('g:title').txt(product.title);
    item.ele('g:price').txt(`${product.price} USD`);
    item.ele('g:availability').txt(product.inStock ? 'in_stock' : 'out_of_stock');
    item.ele('g:link').txt(`https://yourstore.com/products/${product.handle}`);
    item.ele('g:image_link').txt(product.images[0]);
  }

  return root.end({ prettyPrint: true });
}
```

---

### Step 4: Validate before committing

All platforms support a preview/dry-run step — always use it before committing a large import:

- **Shopify built-in**: Review the "X products to create / X to update" summary before clicking Import
- **Matrixify**: The import preview shows which rows have errors with the specific column and issue
- **WP All Import**: Use "Dry Run" mode to preview what will be created/updated
- **BigCommerce**: The upload validation step shows errors before processing

Fix all errors listed in the validation step before proceeding. A partial import — where some rows succeed and others fail — is harder to clean up than re-running a fully corrected file.

---

### Step 5: Monitor and verify

After importing:

1. **Spot-check 5–10 random products** in the admin to verify titles, prices, images, and variants loaded correctly
2. **Check the error log** — Matrixify and WP All Import generate downloadable error reports with row numbers
3. **Verify inventory counts** — if inventory was included in the import, confirm it matches expectations
4. **Test on the storefront** — search for and open 2–3 imported products to verify they display correctly

## Best Practices

- **Always use the platform's sample CSV as your starting template** — hand-crafting a CSV from scratch almost always produces header mismatches
- **Import in batches of 500–1000 products** for large catalogs — easier to debug errors and the platform UI stays responsive
- **Keep a backup of the current catalog** before a large import — export the existing catalog first so you can restore if something goes wrong
- **Don't update inventory via a product import** if you have a separate inventory sync running — two systems updating the same field will conflict
- **Use handles/slugs as the stable unique key**, not titles — product titles change, handles should not
- **Schedule recurring imports at off-peak hours** — large syncs can slow the admin interface during peak business hours

## Common Pitfalls

| Problem | Solution |
|---------|----------|
| CSV import fails with encoding errors | Ensure the file is saved as UTF-8 (in Excel: File → Save As → CSV UTF-8); special characters in product names are the most common cause |
| Images don't appear after import | Images must be hosted at publicly accessible HTTPS URLs at import time; Shopify and WooCommerce download them during import |
| Variants not created correctly | Ensure your CSV has one row per variant (not one row per product); Shopify's CSV format uses repeated handle rows for multiple variants |
| Import creates duplicate products on re-run | Use a tool that supports upsert by handle/SKU (Matrixify, WP All Import); avoid tools that only support insert |
| Inventory reset to 0 after product import | Keep inventory out of the product import CSV if you manage it separately; most platforms let you skip inventory columns |
| Google feed rejected by Merchant Center | Verify required fields: `id`, `title`, `description`, `link`, `image_link`, `availability`, `price`, `brand`, `gtin` or `mpn` |

## Related Skills

- @variant-matrix
- @product-data-modeling
- @multi-warehouse
- @product-content-enrichment