// documentation

Help, guides, and answers.

Search for what you need or scroll through the full manual below. If you're stuck and can't find an answer, open a support ticket.

System requirements

WordPress
6.0 or newer
PHP
7.4 or newer
WooCommerce
7.0+ (optional)
Tested up to
WP 6.9

WooCommerce is only required if you're importing products. Posts, pages, and media work without it.

Step-by-step guides

Longer tutorials that walk through a whole task start to finish:

Installation

From WordPress.org (recommended)

  1. In your WordPress admin, go to Plugins → Add New.
  2. Search for "SimpleImporter".
  3. Click Install Now, then Activate.
  4. A new "SimpleImporter" menu item appears in your admin sidebar. Click it to open the plugin.

Manual upload

  1. Download the plugin zip from WordPress.org.
  2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
  3. Choose the zip file, click Install Now.
  4. Click Activate Plugin when installation completes.

Upgrading to Pro

Pro replaces the free plugin. Your import history, templates, and settings are preserved through the upgrade.

  1. Purchase Pro at checkout.
  2. You'll receive a download link and a license key by email.
  3. Deactivate the free version (do not delete it yet, that step happens after Pro is verified working).
  4. Upload the Pro zip via Plugins → Add New → Upload Plugin.
  5. Activate Pro, then enter your license key in SimpleImporter → Settings.
  6. Once Pro is activated and your data looks right, you can safely delete the free plugin.

Your first import

SimpleImporter is designed so a typical small import is straightforward from upload to finish. Here's the full flow:

  1. Click "New Import" from the SimpleImporter dashboard.
  2. Pick your content type: Products, Posts, Pages, or Media.
  3. Upload your file: Drag and drop a CSV, XLSX, JSON, or XML file. The free version handles unlimited rows for simple products, posts, pages, and media.
  4. Map your columns: Drag column chips from the left onto target fields on the right. Or click "Auto-Map" and SimpleImporter will guess based on column names.
  5. Preview before importing: The right-side preview panel shows what each row will become. Catch mapping mistakes here, not after thousands of rows imported wrong.
  6. Pick your import mode: Insert only, Update only, or Insert-or-Update (default).
  7. Click "Start Import": The import runs in the background. You can navigate away, close the tab, even sleep your computer. It keeps going.

Tip: Start with a 5-10 row test file to learn the flow, then run your real catalog once you trust the mapping.

Mapping columns

Mapping is where your spreadsheet columns get matched to WooCommerce or WordPress fields. SimpleImporter offers three ways to map:

Drag and drop

Your file columns appear as draggable chips on the left side. Drag any chip onto a target field on the right. The chip "fills" the field, and the field shows a coral pill confirming the mapping (for example, "Regular price ← [Price]").

Auto-Map

Click the Auto-Map button to have SimpleImporter guess mappings based on column names. Auto-Map matches common conventions: "sku" maps to SKU, "title" or "name" maps to Product name, "price" maps to Regular price, and so on. You can override any auto-mapped field by dragging a different chip onto it.

Expressions and pills

Some fields need data from multiple columns. SimpleImporter supports inline expressions: type [firstname] [lastname] into a Name field to combine two columns. Or use math: [price] * 0.8 for a 20% discount. Expressions also work for category hierarchies, like [Department] > [Category].

Import modes

SimpleImporter offers three import modes, selected on the mapping screen before you click Start Import:

Insert only

Creates new records for every row. If a row has a SKU that already exists in your store, that row is skipped (or flagged as a duplicate, depending on your settings). Use this when you're importing a fresh catalog and don't want to touch existing products.

Update only

Updates existing records only. If a row has a SKU that doesn't exist in your store, that row is skipped. Use this when you're importing price changes or stock updates and don't want to accidentally create new products.

Insert or update (default)

Existing records (matched by SKU for products, slug for posts) get updated. New records get created. No duplicates. This is what most people want for most imports.

Updates and re-imports

One of SimpleImporter's strengths is handling re-imports cleanly:

  • Re-importing the same file in "Insert or update" mode updates existing rows without creating duplicates.
  • Each import is tagged in your import history. A re-import shows up as a "Re-import of: Original Import" entry, so you can trace lineage.
  • Existing products are matched by SKU. Existing posts and pages are matched by slug or title (configurable in Settings).
  • If you change a column in your file (for example, updated prices), only those changes are written. Unchanged fields aren't touched.

Background processing

Imports run via WordPress's Action Scheduler in small chunks (typically 5-20 rows per chunk, configurable). This means:

  • Safe to close the tab. The import keeps running on the server.
  • Pause anytime. Click the Pause button to halt the import without losing your progress. Resume picks up exactly where you left off.
  • Cancel anytime. Click Cancel to stop the import. Already-imported rows stay imported, but the queue is cleared.
  • Server-friendly. Small chunks prevent PHP timeouts and memory issues on shared hosts.

Imports running slowly?

Action Scheduler runs as fast as your WordPress cron lets it. On low-traffic sites, cron only fires when someone visits the site. Two solutions:

  1. Visit your site in another tab (or have someone else visit it). Each pageview triggers Action Scheduler.
  2. Set up a real server cron job. See WordPress documentation for "WP-Cron alternatives".

Troubleshooting

My import is stuck at X%

Most often, this is WP-Cron not firing. Try these in order:

  1. Open your site in another browser tab and refresh a couple times. Each pageview triggers Action Scheduler.
  2. Go to Tools → Scheduled Actions in WordPress admin. Look for "in-progress" or "pending" actions related to SimpleImporter.
  3. If you see many pending actions, your cron is backed up. Click "Run" on the next pending action manually.
  4. If actions are running but slowly, set up a real server cron via your host (most hosts have a one-click WP-Cron replacement).

My file uploads but the columns look wrong

Usually a file encoding issue. SimpleImporter expects UTF-8 encoded CSVs. If your file is from Excel on Windows, it may be in Windows-1252 (or worse, UTF-16):

  1. In Excel, use File → Save As → choose "CSV UTF-8 (Comma delimited)" as the format.
  2. In Google Sheets, File → Download → CSV (always UTF-8 by default).
  3. In Numbers, File → Export To → CSV → choose UTF-8 in advanced options.

For XLSX files, encoding isn't an issue. If columns still look wrong, check that your column headers are in the first row.

I'm getting duplicate products after importing twice

This happens when SimpleImporter can't match rows to existing products. Check:

  1. Are you in "Insert only" mode? Switch to "Insert or update" to update existing matches.
  2. Did the SKU column get mapped? Without a SKU, products can't be matched.
  3. Were the existing products created by SimpleImporter? If they were created manually or by another tool with different SKUs, matching won't work.

To clean up duplicates, you can export your catalog with SimpleImporter Pro, delete duplicates in Excel, then re-import.

Product images aren't downloading

SimpleImporter downloads images from URLs in your file at import time. Common reasons it fails:

  • The URL returns a 404. Check the URL in a browser. If it doesn't load, the product image source is broken.
  • The URL requires authentication. SimpleImporter can't access password-protected images. Make them publicly accessible.
  • The image is too large. Some hosts limit PHP memory. Resize your images before importing (Photoshop, ImageMagick, or a bulk tool).
  • Your host blocks outbound requests. Check with your host. Most allow them; some shared hosts don't.

I'm seeing "Variations are a Pro feature" in my log

You're importing a file that contains variations (rows with parent SKUs and child variations). The free version of SimpleImporter doesn't support variations and skips those rows silently. Your simple products import normally; just the variation rows are skipped.

To import variable products with their variations, you need Pro. The Pro version handles size and color matrices, automatic parent promotion, and the full variation lifecycle.

I'm getting PHP memory errors

This usually means your host has a low PHP memory limit (often 64MB or 128MB on shared hosting). Solutions:

  1. Reduce SimpleImporter's batch size in Settings (try 5 or 10 rows per batch).
  2. Ask your host to raise memory_limit to 256MB or higher.
  3. Add this to your wp-config.php file: define('WP_MEMORY_LIMIT', '256M');
  4. If you're importing thousands of products, consider running the import during off-peak hours to reduce concurrent load.

My Pro license key isn't activating

Check these in order:

  1. Make sure you're on the Pro plugin (the free version doesn't have a license field).
  2. Copy the license key from your order email exactly. No extra spaces.
  3. Confirm you've deactivated the free SimpleImporter plugin before activating Pro.
  4. Still not working? Open a support ticket with your order number.

Pro is licensed for unlimited sites you own or operate, including client sites, so you don't need to deactivate Pro on other sites to use it on a new one.

My file is too large to upload

WordPress has its own upload size limit, separate from SimpleImporter. Check your host's PHP settings:

  • Look for upload_max_filesize and post_max_size in your PHP configuration.
  • Both should be at least 64MB for medium catalogs (10,000-50,000 rows).
  • For very large files, raise these to 128MB or 256MB.
  • Your host's control panel usually has a one-click setting for this.

Alternative: split your file into smaller chunks and import them in sequence.

Pro features

The Pro version of SimpleImporter unlocks:

  • Variable products with full variation support, attribute pre-scan, and automatic parent promotion.
  • Scheduled imports running hourly, daily, or weekly. Configure once, runs on its own.
  • Remote sources: Google Sheets, Google Drive, Dropbox, FTP, SFTP. Auto-fetch your supplier feeds.
  • Smack! Data Prep tool. A separate workspace for reshaping messy supplier files. Map columns, combine fields, sample rows, then export a clean file ready to import.
  • Yoast SEO field mapping. Import SEO titles, descriptions, focus keywords.
  • Custom Post Types. Import any post type your theme or plugins register.
  • Export to CSV or XLSX. Read existing data out, edit in Excel, re-import.
  • WooCommerce orders, coupons, customers. Not just products.
  • User imports. Bulk-create WordPress users.
  • WPML and Polylang support for multilingual sites.
  • ACF and Meta Box field mapping for advanced custom fields.
  • Brands support for the official WooCommerce Brands plugin.
  • Priority email support. 24 business hour response target, usually faster.

One-time $249 payment. No subscription. Includes lifetime plugin updates and 6 months of priority email support. Optional support renewal is $59.99 per year. See pricing details.

Pro is licensed for unlimited websites you own or operate, including client sites. See our Terms of Service for the full license.

Getting help

Three places to get help, in order of speed:

  1. Search this page first. Most common issues are answered above. Use the search bar at the top, or Cmd+F / Ctrl+F.
  2. Open a support ticket. Fill out the form and send the email. Pro users get priority response within 24 business hours.
  3. WordPress.org support forum. Free users can post at wordpress.org/support/plugin/simpleimporter. We monitor it daily.

When opening a ticket, include: WordPress version, PHP version, SimpleImporter version (Free or Pro), what you tried, what happened, what you expected.