Skip to main content

WordPress/WooCommerce Product Import Guide

Version: 1.0 Last Updated: 2025-01-10 Author: Claude Code Strategic Planner

📋 Table of Contents

  1. Pre-Import Checklist
  2. Import Methods Overview
  3. Method A: WP All Import Plugin
  4. Method B: WooCommerce REST API
  5. Method C: Native CSV Import
  6. Post-Import Actions
  7. Troubleshooting
  8. Reference Files

1. Pre-Import Checklist

✅ Backup Database

CRITICAL: Always backup before importing!

✅ Check Product Categories

Ensure categories exist before importing:
Required Categories for This Project:
  • Meso
  • Filler
  • Căng Chỉ
  • [Other categories from your data]

✅ Verify Image URLs

Check if image URLs are accessible:

✅ Test with 1-2 Products First

ALWAYS test with a small batch before full import:

2. Import Methods Overview

Recommendation: Use WP All Import for this project due to complex pricing structures.

3.1 Installation

Or via WordPress Admin:
  1. Plugins → Add New
  2. Search “WP All Import”
  3. Install & Activate
  4. Install “WP All Import - WooCommerce Add-On”

3.2 Step-by-Step Import

Step 1: Prepare JSON File

Convert your JSON to WP All Import compatible format:

Step 2: Start Import

  1. Navigate to: All Import → New Import
  2. [SCREENSHOT: Select “Upload a file”]
  3. Choose: wp_import.json
  4. Click “Upload file and continue”

Step 3: Configure Import

[SCREENSHOT: Drag & Drop template builder] Post Title:
  • Drag {name} to Title field
Content:
  • Drag {description} to Content field
  • Drag {short_description} to Excerpt field
Images:
  • Drag {image} to Images field
  • Enable “Download images externally”
  • Enable “Use as featured image”

Step 4: WooCommerce Fields

Click “Configure WooCommerce Settings” [SCREENSHOT: WooCommerce field mapping]

Step 5: Categories

[SCREENSHOT: Category mapping]
  • Drag {categories} to Product Categories
  • Select: “Match by name”
  • Enable: “Create categories if they don’t exist”

Step 6: Import Options

[SCREENSHOT: Import settings]
Processing Mode:
  • Choose: “Process in background” (recommended for >100 products)

Step 7: Run Import

Click “Continue & Run Import” [SCREENSHOT: Progress bar]
  • Monitor progress in real-time
  • Receive email when complete

3.3 Advanced Features

Automatic Scheduling

Custom Field Mapping


4. Method B: WooCommerce REST API

4.1 Setup Authentication

Or via Admin:
  1. WooCommerce → Settings → Advanced → REST API
  2. Click “Add Key”
  3. Description: “Product Import”
  4. Permissions: Read/Write
  5. Click “Generate API Key”
  6. COPY Consumer Key & Secret (you won’t see them again!)

4.2 Prepare Import Script

Create /tmp/import_products.js:

4.3 Run Import Script

4.4 Update Existing Products

4.5 Batch Import (WooCommerce 3.0+)


5. Method C: Native CSV Import via WooCommerce

5.1 Prepare CSV Template

Create /tmp/products_import.csv:

5.2 Convert JSON to CSV

Create /tmp/json_to_csv.py:
Run conversion:

5.3 Import via WooCommerce

  1. Navigate to: WooCommerce → Products → Import
  2. [SCREENSHOT: CSV upload screen]
  3. Choose products_import.csv
  4. Click “Upload file and continue”

5.4 Map CSV Columns

[SCREENSHOT: Column mapping screen] Required Mappings:
  • Name → Name
  • SKU → SKU
  • Regular price → Regular price
  • Categories → Categories
  • Images → Images

5.5 Run Import

Click “Run Import” [SCREENSHOT: Import progress]

6. Post-Import Actions

6.1 Verify Prices

6.2 Check Sale Prices

6.3 Test Product Pages

6.4 Update Inventory

6.5 Regenerate Thumbnails

6.6 Clear Cache


7. Troubleshooting

7.1 Common Issues

Issue: Images Not Importing

Symptoms:
  • Products imported but no images
  • Broken image icons
Solutions:
  1. Check image URL accessibility:
  1. Enable “Download images externally”:
    • WP All Import: Images section → Enable “Download externally hosted images”
  2. Check file permissions:
  1. Increase memory limits:

Issue: Duplicate SKUs

Symptoms:
  • Import fails with “SKU already exists”
  • Products not updating
Solutions:
  1. Find duplicates:
  1. Remove duplicates:
  1. Update import strategy:
    • Enable “Update existing products”
    • Match by: SKU

Issue: Categories Not Mapping

Symptoms:
  • Products import but no categories
  • All products in “Uncategorized”
Solutions:
  1. Check category slugs:
  1. Create missing categories:
  1. Verify mapping:
    • WP All Import: Categories → Match by “name” (not slug)
    • Enable “Create categories if they don’t exist”

Issue: Import Timeout

Symptoms:
  • Import stops after 30-60 seconds
  • Only some products imported
Solutions:
  1. Increase PHP limits:
  1. Use background processing:
    • WP All Import: Enable “Process in background”
    • Set lower batch size: 50 products per batch
  2. Split large files:

Issue: Special Characters Not Displaying

Symptoms:
  • Vietnamese characters show as question marks
  • Accented letters broken
Solutions:
  1. Check database charset:
  1. Convert to UTF-8:
  1. Set charset in wp-config.php:

7.2 Error Codes Reference

7.3 Enable Debug Mode


8. Reference Files

8.1 Data Sources

New Products to Add:
Bruno Vassari Products:

8.2 File Formats

Expected JSON Structure

8.3 Quick Reference Commands


9. Best Practices

✅ DO:

  • Always backup before importing
  • Test with 2-5 products first
  • Use unique SKUs
  • Optimize images before import (max 1500px, under 500KB)
  • Clean data before import (remove special chars, trim spaces)
  • Use background processing for >100 products
  • Monitor server resources during import
  • Keep import logs for troubleshooting

❌ DON’T:

  • Import thousands of products without testing
  • Use spaces or special chars in SKUs
  • Skip category creation
  • Ignore error messages
  • Import during peak traffic hours
  • Forget to clear cache after import
  • Assume everything worked without verification

10. Support Resources

Documentation: Tools: Community:
  • WordPress.org Forums
  • WooCommerce Slack Community
  • Stack Overflow (tag: woocommerce)

Appendix A: Import Workflow Checklist

Before Import:

  • Backup database
  • Backup uploads folder
  • Verify image URLs accessible
  • Create all categories
  • Test with 1-2 products
  • Review JSON structure
  • Clean data (remove duplicates, fix SKUs)

During Import:

  • Monitor progress
  • Check for errors
  • Verify server resources
  • Watch error logs

After Import:

  • Verify product count
  • Check sample products
  • Test prices (regular & sale)
  • Verify categories
  • Test product pages
  • Check images load
  • Update inventory
  • Clear cache
  • Test checkout
  • Revoke API keys (if used)

End of Guide For questions or issues, refer to troubleshooting section or consult WordPress/WooCommerce documentation.