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.