saleor/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