data-importer

Data Importer

Overview

This skill helps you convert product data from external sources (CSV files, spreadsheets, Shopify exports) into Saleor's config.yml format. It walks through format detection, column mapping, and validation before generating output.

When to Use

• "I need to import products from a CSV"
• "How do I convert my spreadsheet to config.yml?"
• "I'm migrating from Shopify"
• "I have product data in Excel"
• "How do I bulk import products?"
• When NOT writing config.yml from scratch -- use configurator-schema instead
• When NOT designing product types -- use product-modeling first

Core Workflow

1. Detect format -- CSV, Excel, JSON, or unknown
2. Extract columns -- read headers and sample data
3. Map interactively -- you confirm field mappings
4. Transform -- convert to Saleor schema
5. Validate -- check for issues before output

File Handling

Excel (.xlsx)

Excel files need conversion. Export as CSV from Excel/Sheets, or:

python3 -c "import pandas as pd; pd.read_excel('$FILE').to_csv('${FILE%.xlsx}.csv', index=False)"

CSV

Read directly to inspect headers and sample rows.

Field Mapping

Don't assume column names. The importer will:

1. Show you all columns with sample values
2. Ask which column maps to each Saleor field
3. Mark unmapped columns as potential attributes

Required Fields

Saleor Field	Typical Source Columns
product.name	"name", "title", or any descriptive column
product.slug	Generated from name, or "handle"/"ID" column
variant.sku	"SKU", "External ID", "Code"
productType	"type" column or you specify it

Optional Fields

Field	Notes
price	If missing, imports as catalog-only
quantity	If missing, skips stock tracking
category	From category/region column
description	If present in source data
Other columns	Become product attributes

Output Structure

productTypes:
  - name: "[from type column or your input]"
    productAttributes: [unmapped columns become attributes]

categories:
  - name: "[from category column]"
    slug: "[generated]"

products:
  - name: "[from name column]"
    slug: "[generated or from ID]"
    productType: "[reference]"
    variants:
      - sku: "[from SKU column]"
        channelListings: [if price exists]
        stocks: [if quantity exists]

Special Cases

• No price column -- imports as catalog-only; add pricing later
• No SKU column -- generates from name or uses any unique ID column
• Unknown columns -- presented to you as potential attributes
• Multiple rows with same product -- grouped as variants of one product

Common Mistakes

Mistake	Fix
Assuming column names without checking	Always inspect headers first -- column names vary wildly between sources
Not handling missing SKUs	Generate SKUs from product name + variant attributes, or use a unique ID column
Importing without validating first	Review the generated YAML before deploying -- check for duplicates and missing fields
Duplicate products from multi-row variants	Ensure rows sharing a product name are grouped as variants, not separate products
Forgetting to create product types first	Design your product types before importing -- use product-modeling skill

Validation Checklist

Before generating output, verify:

• All products have names
• All variants have unique SKUs
• Product type references are valid
• No duplicate slugs

Reference Files

• references/csv-patterns.md -- CSV/Excel parsing techniques
• references/field-mapping.md -- Mapping strategies for various data shapes
• references/shopify-format.md -- Shopify-specific handling
• references/transformations.md -- Data transformation rules

See Also

Related Skills

• configurator-schema - Config.yml structure and field requirements
• product-modeling - Product type design before importing
• saleor-domain - Entity relationships and identifier rules