Getting Started

Choosing your unique identifier

Published · Last updated

The unique identifier is the field (or combination of fields) Super Speedy Imports uses to decide whether a row should UPDATE an existing post or INSERT a new one. Get this right and re-imports are clean. Get it wrong and every re-import creates duplicates.

In the import screen this lives in its own section at the top of the mapping form, headed “How should existing products be matched?” (the heading names your post type — “posts”, “pages”, and so on). You pick a ready-made option from the dropdown, and a plain-English line confirms the consequence: “Rows with the same SKU update the existing product. Rows with a new SKU create a new one.”

This is the single most important decision when setting up an import.

What it does

On every run, SSI’s match-existing stage looks at each CSV row and asks: “Does WordPress already have a post with this unique identifier value?”

  • Yes → store that post’s ID on the batch row → the later update-posts / update-postmeta stages will UPDATE that post.
  • No → leave the post_id blank → insert-posts / insert-postmeta will create a new post.

Without a unique identifier, every re-import would duplicate every row.

The fallback — _sku

If you don’t set an explicit unique identifier, SSI falls back to the _sku postmeta key — but only when _sku is actually mapped. This is what WooCommerce stores SKUs under, so for a typical product import where you’ve mapped a SKU column it Just Works:

"post_meta": {
    "_sku": "SKU",
    "_regular_price": "Regular_Price"
}

With this config, the value in your CSV’s SKU column becomes the _sku postmeta — and, since no explicit unique identifier is set and _sku is mapped, SSI uses that as the unique identifier automatically.

If neither an explicit unique identifier nor a _sku mapping is present, this fallback does not apply — you must set the unique identifier explicitly (see below).

Constraint: SKU values must be unique across all products. If two CSV rows have the same SKU, SSI dedups them at load time by appending -2, -3, etc. (Watch the CLI output for the Fixed N duplicate post_name values count.)

Choosing a match option

The “How should existing products be matched?” dropdown offers the ready-made options that fit your post type. For a WooCommerce product import you get:

  • SKU (the default) — matches on _sku, the right choice for almost every store.
  • GTIN / UPC / EAN / ISBN — matches on the WooCommerce global unique ID (_global_unique_id), for catalogues keyed on a barcode rather than a SKU.

For posts and pages the default is Post title, with a Post title + category option for feeds where the same title appears under different sections. Whichever you pick, SSI matches each CSV row against the field existing items already carry, so a re-import updates them instead of duplicating.

Custom — matching on your own combination of fields (Pro)

Choose Custom… to build the identifier yourself from any combination of post fields (Title, Slug), postmeta (SKU, GTIN) and taxonomies. Tick the fields that together identify a row; an item matches only when all of the chosen fields are equal. This is the composite case — for example SKU + colour + size, when the same SKU repeats across variants and no single field is unique on its own.

Every field you include must also be mapped in the import. If you include a taxonomy, the run must resolve terms (Full, Only update, Only insert or Re-sync taxonomies — not the “prices only” or “images only” modes).

The Custom builder is a Pro feature. The Lite edition matches on the ready-made options above.

Note: SSI no longer supports a raw CSV column or a PHP function as the identifier (both were removed in 2.57). Anything you used to express that way is now covered by a preset or by the Custom composite builder.

What happens with a blank identifier

By default SSI treats a blank match value as a fatal data-quality issue. The matcher section carries the control for this — “If a row has a blank match value:” — with two choices: Stop the import so I can fix the file (the recommended default) or Skip that row and continue. On the default, any CSV row with a blank value in the configured identifier makes the import abort during load-csv:

Import aborted — 5 row(s) have a blank unique identifier.
Every row must have a non-empty value in column 'SKU'.

Row 12: blank value in unique identifier column 'SKU'
Row 47: blank value in unique identifier column 'SKU'
...

The abort is by design — silently inserting rows with blank identifiers would create posts that can’t be matched on the NEXT re-import, leading to duplicates forever. Fix the CSV (fill in the missing identifiers or remove the rows) and re-run.

Things to watch for

Don’t change the unique identifier between runs

If your first import used SKU as the identifier, every post got _ssi_unique_item_id = <sku-value> attached. If you then change the identifier to a different column and re-import, match-existing will look for the NEW identifier — won’t find anything — and INSERT every row as a new post. Duplicate catalog.

If you genuinely need to switch identifiers, plan a migration: bulk-update the existing _ssi_unique_item_id postmeta to the new scheme via SQL or WP-CLI before the first re-import on the new identifier.

Trim whitespace in your CSV

SSI matches identifiers byte-for-byte. A SKU "ABC-123 " (trailing space) and "ABC-123" are different identifiers. Most spreadsheet exports preserve trailing whitespace; check your CSV.

Case sensitivity depends on your DB collation

abc-123 and ABC-123 may or may not match depending on whether your WordPress database uses a case-sensitive collation. Default WP collation (utf8mb4_unicode_520_ci) is case-insensitive, so they’ll match. Custom collations may not. When in doubt, normalise to one case in your CSV.

SSI’s behaviour on duplicate identifiers within ONE CSV

If your CSV has two rows with the same SKU (a real data bug, but it happens), SSI’s load-csv finalisation dedups by appending -2, -3, etc. to the duplicates’ identifier values. Both rows get imported, but with slightly different identifiers — which means each becomes a separate WP post. Watch the CLI’s Fixed N duplicate post_name values line after load-csv. A non-zero count indicates a CSV that should be cleaned up.

Summary checklist

  • ✓ Pick a field whose values are stable, unique, and present on every row.
  • ✓ If no single field is unique, use Custom… to combine several (e.g. SKU + colour + size) so the combination is unique.
  • ✓ NEVER change the unique identifier between runs without a migration plan.
  • ✓ Trim whitespace and normalise case before importing.
  • ✓ Watch for the “blank unique identifier” abort on first run — fix the CSV, don’t bypass the check.

What’s next

  • Quick start — importing products: shows where this fits in the bigger setup flow.
  • How imports work — the stage pipeline: explains why match-existing runs WHEN it does and what depends on it.
  • Stage selection presets: lets you run just the matching+update flow without re-doing the full pipeline.
  • Fixing Slow WooCommerce Imports — the hub guide, including the fixes that work whichever importer you use.

Comments

▲
▼
1/1