Getting Started with CSV Importer

Skill level: Beginner
Time to complete: 10–20 minutes
Plugin location: Tools → CPT CSV Importer

What You’ll Learn

  • How to prepare a CSV file for import
  • How to create a brand-new Custom Post Type from your CSV structure
  • How to import CSV data into an existing Custom Post Type
  • What the plugin creates and where it stores things

Before You Begin

Prepare Your CSV

CSV Importer requires a header row — the first row of your file must contain column names. These names become your field labels and meta key names, so make them descriptive.

Good CSV structure:

Product Name, Category, Brand, SKU, Price, Description
Widget Pro, Tools, Acme, WP-001, 29.99, A professional-grade widget
Widget Lite, Tools, Acme, WL-001, 9.99, An entry-level widget
Gadget X, Electronics, Globex, GX-100, 149.99, A next-gen gadget

Tips for best results:

  • Use simple, descriptive header names (avoid special characters other than spaces and underscores)
  • Columns where many rows share values (like Category or Brand) work well as taxonomies
  • Columns with unique values per row (like SKU or Description) work well as meta fields
  • To store multiple taxonomy terms in one cell, separate them with a consistent character like a pipe | or semicolon ;

Multi-value example:

Product Name, Tags
Widget Pro, tools | hardware | professional
Gadget X, electronics | wireless | portable

Supported File Formats

  • Extension: .csv
  • Encoding: UTF-8 recommended (with or without BOM)
  • Delimiters: Comma (default), Tab, Semicolon, Pipe
  • Max size: Governed by your PHP upload_max_filesize and max_execution_time limits

Option A: Create a New CPT from Your CSV

Use this when you want to turn your spreadsheet structure into a fully working custom post type — with no coding required.

Step 1 — Go to the Importer

Navigate to Tools → CPT CSV Importer in the WordPress admin.

Step 2 — Choose “Create New CPT from CSV”

In the Mode section at the top of the page, select Create new CPT from CSV. This unlocks the full creation wizard.

Step 3 — Upload Your CSV

  1. Click Choose File and select your CSV
  2. Select the CSV Delimiter that matches your file (usually Comma)
  3. Select the Multi-value Delimiter — choose Auto-detect if you’re unsure, or manually pick the character you used to separate multiple taxonomy terms per cell
  4. Set Duplicate Handling — for a fresh import, “Always create new” is fine; if you’ll re-import later, “Skip existing” or “Update existing” prevent duplicates

Click Upload & Analyse.

Step 4 — Review Column Types

The plugin scans your data and suggests a type for each column:

TypeWhat it means
TitleThis column becomes the post title (one only)
TaxonomyCreates a taxonomy; values become filterable terms
Text (Meta)Stored as post meta; used for unique per-record values
SkipColumn is ignored during import

The plugin makes these suggestions based on your data’s cardinality (how many unique values the column has). Low-cardinality columns (many repeating values) are flagged as taxonomies. High-cardinality columns are flagged as meta.

To change a suggestion: Click the radio button for the type you want. Changes are reflected immediately with row border colours:

  • Green = Title
  • Blue = Taxonomy
  • Grey = Meta
  • Red = Skip

Important: You must have exactly one Title column selected. JavaScript enforces this.

For taxonomy columns, check Multi-value if a single cell can contain multiple terms (e.g., tools | hardware).

You’ll also see a CPT Name field at the top. Enter a plural name for your post type (e.g., “Products”, “Business Listings”, “Events”). A slug preview updates live — this is the post type key used internally (e.g., business_listings).

Choose your Duplicate Handling preference and click Create Post Type & Continue.

Step 5 — Import

The plugin registers the CPT and taxonomies, then runs the import. A results summary shows:

  • Created: New posts added
  • Updated: Existing posts updated (if using Update mode)
  • Skipped: Rows skipped due to existing title match
  • Errors: Any rows that failed

All imported posts are created with status Publish.

What Was Created

After the wizard completes, you have:

  • A new post type visible under its own menu item in the admin sidebar
  • All taxonomy columns registered as filterable taxonomies
  • All meta columns registered as admin list table columns
  • All CSV data imported as published posts
  • The CPT definition stored in WordPress options (persists across updates)

Option B: Import into an Existing CPT

Use this if your CPT already exists (registered by another plugin, a theme, or your own code) and you just want to populate it with CSV data.

Step 1 — Choose “Import into Existing CPT”

On the main importer page, ensure the mode is set to Import into existing CPT (this is the default).

Step 2 — Select Your Post Type

Choose the target post type from the dropdown. All registered public post types are listed, including WordPress built-ins (post, page) and any CPTs from other plugins.

Step 3 — Upload Your CSV

Same as Option A — upload your file, select delimiter options, and choose duplicate handling.

Step 4 — Map Columns

The mapping screen shows each column header and a dropdown to assign it:

Mapping optionResult
Post TitleSets the post_title field
SkipColumn ignored
[Taxonomy name]Values assigned as terms to that taxonomy
Custom Meta FieldStored as post meta — you specify the key name

For taxonomy columns, the multi-value delimiter you selected in Step 3 is used to split cell values.

Tip: Use the dry run checkbox to preview results before committing. The import runs but no posts are created — you see what would happen.

Click Run Import (or Dry Run).

Step 5 — Review Results

Same results summary as Option A. Repeated imports with “Skip existing” are safe — already-imported rows are left untouched.

Viewing Your Imported Data

Once import is complete:

  1. In the admin sidebar, find your post type (e.g., “Products”)
  2. Click it to open the list table
  3. You’ll see custom columns for each taxonomy and meta field
  4. Use the filter dropdowns above the table to filter by taxonomy terms

For CPTs created by this plugin, the columns appear in the order you defined in Manage Fields.

Re-Importing / Updating Data

You can run the importer again at any time against the same CPT:

  • Skip existing: Safe to re-run; already-imported rows are untouched; only new rows are added
  • Update existing: Matches by post title and overwrites meta/taxonomy values
  • Always create new: Creates duplicates — only use this if you intentionally want all rows added regardless

Deleting a CPT Created by This Plugin

Go to Tools → CPT CSV Importer → Registered Types (the table at the bottom of the main page).

Click Delete next to the CPT you want to remove.

What happens:

  • The CPT definition is removed from WordPress options
  • The CPT and its taxonomies are unregistered on next page load
  • Existing posts and terms are NOT deleted — they remain in the database

If you want to fully remove all posts, delete them from the post list table before deleting the CPT registration.

Troubleshooting

My CSV isn’t uploading

  • Check your PHP upload_max_filesize and post_max_size settings in php.ini
  • For large files, also increase max_execution_time

My columns are being assigned the wrong types

  • Override any suggestion using the radio buttons on the Analyse Columns screen
  • The plugin’s heuristics are guides, not hard rules

Taxonomy terms aren’t being created

  • Check the multi-value delimiter setting matches what’s in your data
  • If your terms contain commas, use a different delimiter (pipe | recommended)

Import ran but I don’t see the CPT in the menu

  • Try refreshing the page — this triggers re-registration on init
  • Check Tools → CPT CSV Importer → Registered Types to confirm the CPT is listed

Duplicate posts are being created

  • Switch duplicate handling to “Skip existing” or “Update existing”
  • Duplicate detection is based on post title — ensure your title column has consistent values between imports

Next Steps