Controlling which stages of an import actually run
Every Super Speedy Imports run is a pipeline of independent stages — load the CSV, match existing posts, write new ones, update changed ones, attach images, etc. By default all of them run on every import. From 2.53 you can narrow that down to just the stages you actually need, either by saving a preset on the import config (admin UI) or by passing a one-off list on the CLI.
This is the right tool when:
- You’re running a daily price feed and don’t want full post updates / image checks.
- You want to add new items only and never touch what’s already in the DB.
- You want to update existing items but never grow the catalog from the CSV.
- Your media library got cleared and you want to re-attach images without touching anything else.
- You renamed taxonomies upstream and want to refresh term relationships without re-importing post bodies.
Table of Contents
Setting the import mode in the admin UI
- Open Super Speedy Imports in WP admin.
- Select your import from the Existing imports dropdown.
- Scroll to the Additional Options section.
- Find Import mode. Click the
?next to the label for the full per-preset breakdown of which stages each option runs. - Pick the preset that matches what you want to do.
- Click Save Import.
The next time this import runs (whether kicked off via the admin “Run Now” button or via wp ssi <id> on the CLI), only the stages allowed by that preset will execute.
The presets
| Preset | What it does | Use case |
|---|---|---|
| Full import (default) | Every registered stage | First imports, full syncs |
| Only insert new items | Full pipeline minus the update path. Runs load-csv → import-taxonomies → match-existing → insert-posts → insert-postmeta → upsert-relationships → all three image stages (attach-existing-images, upload-remote-images, attach-gallery-images) → fix-attributes → post-import-cleanup. Only update-posts / update-postmeta are skipped — so taxonomies, relationships, images and attributes are still fully processed for the newly inserted items. |
Catalog top-ups where existing items must stay untouched but new items need full processing (including image downloads) |
| Only update existing items | Runs load-csv → import-taxonomies → match-existing → update-posts → update-postmeta → upsert-relationships → fix-attributes → post-import-cleanup. Only insert-posts / insert-postmeta are skipped — taxonomies and attributes are still re-processed for matched items. (Note: the image stages do not run in this preset.) |
Price / stock / attribute refresh where the CSV shouldn’t grow the catalog |
| Update prices / postmeta only | load-csv → match-existing → update-postmeta |
Daily price / stock feeds — cheapest update path |
| Re-sync taxonomies only | load-csv → import-taxonomies → match-existing → upsert-relationships |
After bulk-renaming categories or fixing taxonomy slugs upstream |
| Refresh images only | load-csv → match-existing → image stages |
After the media library got cleared or attachments were regenerated |
All presets except “Refresh images only” include post-import-cleanup (the WP / WC cache + lookup-table refresh) when that stage is available.
What gets skipped is template-specific
The preset stage lists reference stages by name. Stages your template doesn’t register for (e.g. fix-attributes doesn’t exist for a plain post-type import; image stages don’t exist when no media field is mapped) are simply not in the run — same as today.
Overriding the preset on a one-off CLI run
CLI input always wins over the saved preset. Useful when you’ve configured the import for daily price-only refresh but need to run a one-off full import, or vice versa.
Run all stages from a comma-separated list
wp ssi <import-id> load-csv,match-existing,update-postmeta
The named stages run in their normal priority order (you can’t reorder by re-ordering the list). Stages not in the list are skipped, regardless of what the saved preset says.
Run a single stage
wp ssi <import-id> update-postmeta
Useful for re-running just one stage after a partial / failed run, or diagnosing performance of one stage in isolation.
Run the default (whatever the preset says)
wp ssi <import-id>
No stage argument = use whatever the saved preset dictates. The “Full import” default = every registered stage.
Verifying what will actually run
When a preset narrows the stage list, the CLI prints a banner near the start of the run:
Import mode: prices_only — running 3 of 12 registered stages.
When you pass an explicit stage list, the CLI confirms it:
Running selected stages: load-csv, match-existing, update-postmeta
So you can always check the banner before the import gets deep into work.
Precedence
When multiple things want to control which stages run, here’s the order:
--delete-all flag ← strongest. Runs ONLY process-deletes.
overrides
CLI explicit stage list ← strong. Per-run override.
overrides
Saved Import mode preset ← persistent default for this import.
overridden by
Template's full registered stage list ← what happens when nothing's set.
--delete-all is intentionally the strongest because it expresses destructive, “I really mean it” intent. Everything else is just filtering which stages run.
Examples
Daily price feed automated via cron
Set the import’s Import mode to Update prices / postmeta only, then:
# In cron, every morning at 4am:
0 4 * * * cd /var/www/site/htdocs && wp ssi 7
The saved preset means each cron run loads the CSV, matches existing products, updates their postmeta (which includes _regular_price, _sale_price, _stock), and runs the cache flush. No image checks, no post-body updates, no insert path. Minutes instead of hours.
One-off full sync without changing the saved preset
wp ssi 7 load-csv,import-taxonomies,match-existing,update-posts,update-postmeta,insert-posts,insert-postmeta,upsert-relationships,attach-existing-images,upload-remote-images,attach-gallery-images,fix-attributes,post-import-cleanup
That’s a mouthful. If you find yourself doing this often, just temporarily flip the saved preset to “Full import” in the admin UI before running, then flip it back.
Adding new SKUs without touching anything existing
Set Import mode to Only insert new items. The match-existing stage still runs (it has to, to identify which CSV rows are new vs existing), but the update-* stages don’t. Existing items stay exactly as they are.
Resuming a failed image stage
If upload-remote-images died mid-stage, you don’t have to re-run the whole import. The batch table is still populated:
wp ssi 7 upload-remote-images
Picks up where the previous run left off (rows with non-null post_id and non-empty featured_image that don’t yet have an _thumbnail_id).
What about per-stage on/off toggles?
The 2.53 release ships preset-only. The design doc considered exposing per-stage checkboxes in the admin UI (alongside the preset dropdown) for fully-custom selections, but for now: use the preset that’s closest to what you want, then override the difference with a one-off CLI run when needed. If you find yourself wanting a combination that’s not in the preset list, file feedback so a future release can either add the preset or ship the per-stage toggles.
The preset → allowed-stages map is exposed as a static method:
$presets = SSI_ImportTemplate::getStagePresets();
// returns: ['full' => null, 'only_insert' => [...], ...]
The null value for full means “no filter, run everything registered”. Other values are arrays of stage names — stages NOT in the list are removed from the filtered set.
The mechanism is the ssi_filter_stages_to_run filter at priority 5. Your add-on can:
// Override a preset entirely or add a new one
add_filter('ssi_filter_stages_to_run', function($stages, $config, $template) {
if (!empty($template->additional_options['import_mode'])
&& $template->additional_options['import_mode'] === 'my_custom_preset') {
return array_intersect_key($stages, array_flip([
'load-csv', 'match-existing', 'my-custom-stage',
]));
}
return $stages;
}, 4, 3); // priority 4 — runs BEFORE the core preset filter at 5
Or just hook in at priority 7 to compose on top of whatever preset is active.
Cross-references
import-template-abstract.php:getStagePresets()— the canonical preset → stages map.run-import.php:ssi_run_parallel()— where the preset filter is installed at priority 5.
