Product Import

Import products from JSON, CSV, or sync directly from Shopify.

Overview

The hyperfold catalog product-import command loads products into your Hyperfold catalog. During import, products are validated, enriched with semantic embeddings, and indexed for vector search.

Import automatically generates semantic embeddings for each product. This enables AI agents to find products using natural language queries.

JSON Import

Import products defined in JSON files:

# Import a single product from JSON
$ hyperfold catalog product-import ./products/shoe.json

> [Parse] Reading product file...
> [Validate] Schema validation... OK
> [Enrich] Generating embeddings...
> [Store] Writing to Firestore...
> [Index] Updating Vector Search index...

✓ Product imported: prod_aero_x2

# Import a directory of products
$ hyperfold catalog product-import ./products/

> [Scan] Found 47 product files
> [Batch] Processing in parallel (8 workers)...
> [Progress] 47/47 complete

✓ Imported 47 products
  New: 42
  Updated: 5
  Errors: 0

JSON File Structure

JSON files can contain a single product object or an array of products. See Product Specification for the complete schema.

CSV Import

Import from spreadsheets or exports from other systems:

# Import from CSV file
$ hyperfold catalog product-import ./products.csv --format=csv

> [Parse] Reading CSV file (1,247 rows)...
> [Map] Mapping columns to schema...
> [Validate] Validating 1,247 products...
> [Batch] Importing in batches of 100...

✓ Imported 1,247 products

# Specify column mapping
$ hyperfold catalog product-import ./products.csv \
  --format=csv \
  --map="SKU:product_id" \
  --map="Title:name" \
  --map="Price:pricing.list_price" \
  --map="Stock:inventory.quantity"

CSV Format

The CSV should have headers matching field names:

product_id,name,description,list_price,currency,quantity,category
prod_001,Running Shoes,Professional marathon shoes,180.00,USD,500,footwear
prod_002,Training Jacket,Lightweight workout jacket,89.99,USD,200,apparel
prod_003,Water Bottle,32oz insulated bottle,24.99,USD,1000,accessories

CSV Column	Maps To
`product_id`	product_id
`name`	name
`list_price`	pricing.list_price
`cost`	pricing.cost
`quantity`	inventory.quantity
`category`	semantics.category

Shopify Sync

Sync products directly from your Shopify store:

# Connect Shopify store (one-time setup)
$ hyperfold integrate add shopify \
  --store="acme-sports.myshopify.com" \
  --api-key="shpat_xxx"

> [OAuth] Connecting to Shopify...
> [Verify] Checking API permissions...
✓ Shopify connected: acme-sports.myshopify.com

# Sync all products from Shopify
$ hyperfold catalog product-import --source=shopify

> [Shopify] Fetching products (page 1/15)...
> [Shopify] Fetching products (page 15/15)...
> [Transform] Converting to Hyperfold schema...
> [Enrich] Generating semantic embeddings...

✓ Synced 1,489 products from Shopify
  New: 23
  Updated: 1,466
  Unchanged: 0

# Enable automatic sync
$ hyperfold catalog product-import --source=shopify --sync=webhook

> [Webhook] Registering product update webhook...
✓ Auto-sync enabled. Product changes will sync automatically.

Shopify sync requires the read_products scope. Enable webhooks for automatic sync of product updates.

Batch Operations

Control how imports handle existing products:

# Dry run to preview changes
$ hyperfold catalog product-import ./products/ --dry-run

> [Preview] Would import 47 products:
>   prod_aero_x2: NEW
>   prod_storm_gt: UPDATE (price: $150 → $165)
>   prod_basic_tee: UNCHANGED

# Upsert mode (update existing, insert new)
$ hyperfold catalog product-import ./products/ --upsert

# Insert only (skip existing)
$ hyperfold catalog product-import ./products/ --insert-only

# Update only (skip new)
$ hyperfold catalog product-import ./products/ --update-only

# Delete products not in import file
$ hyperfold catalog product-import ./products/ --sync-delete

> ⚠ WARNING: This will delete 12 products not in import.
> Continue? [y/N] y

Import Modes

Mode	Existing	New
`--upsert` (default)	Update	Insert
`--insert-only`	Skip	Insert
`--update-only`	Update	Skip
`--sync-delete`	Update or Delete	Insert

Validation & Errors

Control error handling during import:

# Continue on errors
$ hyperfold catalog product-import ./products/ --continue-on-error

> [Error] prod_bad_001: Invalid price format
> [Error] prod_bad_002: Missing required field 'name'
> [Continue] Skipping 2 invalid products...

✓ Imported 45/47 products
✗ Failed 2 products (see errors.json)

# Output errors to file
$ hyperfold catalog product-import ./products/ \
  --continue-on-error \
  --error-file=./import-errors.json

# Strict mode (fail on first error)
$ hyperfold catalog product-import ./products/ --strict

> [Error] prod_bad_001: Invalid price format
✗ Import aborted. Fix errors and retry.

Enrichment Options

Control semantic enrichment during import:

# Skip automatic enrichment (faster)
$ hyperfold catalog product-import ./products/ --no-enrich

# Force re-enrichment of existing products
$ hyperfold catalog product-import ./products/ --force-enrich

# Enrich only (no schema changes)
$ hyperfold catalog enrich --all

> [Enrich] Processing 1,489 products...
> [Embedding] Generating vector embeddings...
> [Semantic] Extracting visual tags from images...

✓ Enriched 1,489 products

After importing, optimize your catalog for agents with catalog optimize.

Search Documentation