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. 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.

Setting the import mode in the admin UI

1. Open Super Speedy Imports in WP admin and go to the Config tab.
2. Select your import in the Import Name dropdown.
3. Scroll to the Additional Options section.
4. Find What should this import do? (the import mode). Click the ? next to the label for a summary of each option.
5. Pick the mode that matches what you want to do.
6. Click Save Import.

The next time this import runs (whether kicked off via the admin “Run Now” button, a schedule or wp ssi <id> on the CLI), only the stages allowed by that mode will execute. The one exception is a CLI run that names its own stages (below).

For exactly what each mode writes to new and matched items, stage by stage, see Import modes and what each stage writes.

The modes

Every mode also keeps post-import-jobs, the After Import tasks. An import with a recurring remote source keeps source-fetch, and an XML or JSON import keeps xml-to-csv (Reading the source file), in front of load-csv. process-deletes runs only in the default mode, whatever the delete checkbox says.

What gets skipped is template-specific

The mode stage lists reference stages by name. Stages your template doesn’t register (for example fix-attributes for a plain post-type import, or the image stages when no media field is mapped) are simply not in the run.

Overriding the preset on a one-off CLI run

A stage list on the CLI replaces the saved preset for that run: the stages you name run, whatever the saved mode says, and the saved mode is left as it is. 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 several 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. A stage the saved mode leaves out still runs when you name it: on an import saved as Only update prices & other item details, wp ssi <import-id> load-csv,match-existing,insert-posts creates the new items.

The safety checks still apply to your list. For example, an import matched on a custom (composite) identifier refuses a list without match-existing, because matching cannot happen without it.

Stage names must be exact

Stage names are the hyphenated names shown in this article and in the CLI output (load-csv, not load_csv). If any name in the argument is not a stage this import has, the command stops before doing anything, exits with code 1 and prints an error naming the unknown entry and listing the import’s stages in run order. A posts import, for example, has no fix-attributes.

A stage the import has but that has nothing to do for its configuration, such as insert-postmeta when no custom fields are mapped or fix-attributes when no attributes are mapped, is not run, and the CLI says so:

Listed stages not run (nothing to do for this import's configuration): fix-attributes

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 mode dictates. The default mode runs every registered stage.

A single name that is a utility rather than a stage (save-posts, sanitize-terms, list-files) runs that utility on its own; utilities cannot be combined with stages in a list.

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 6 of 18 registered stages.

When you pass an explicit stage list, the CLI confirms it, and on an import saved with a narrower mode it says the mode is not used for this run:

Running selected stages: load-csv, match-existing, update-postmeta
Import mode: prices_only is not applied to this run; running the stages listed on the command line.

The counts depend on which stages the import registers. 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; replaces the saved mode.
    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 mode to Only update prices & other item details, 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), recomputes variable price ranges and runs the After Import tasks. No image checks, no post-body updates, no new items. Minutes instead of hours.

One-off full sync without changing the saved preset

For a product import:

wp ssi 7 load-csv,import-taxonomies,match-existing,handle-slug-duplicates,update-posts,insert-posts,update-postmeta,insert-postmeta,attach-existing-images,upload-remote-images,upsert-relationships,process-variable-products,assign-product-type,attach-gallery-images,fix-attributes,process-deletes,sync-variable-prices,post-import-jobs

That’s a mouthful. If you find yourself doing this often, temporarily switch the saved mode to Update existing items and create new ones in the admin UI before running, then switch it back. An explicit stage list runs only the stages you name, so include post-import-jobs when you want the After Import tasks.

Adding new SKUs without touching anything existing

Set the mode to Only create 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 admin UI offers presets only. Use the preset that’s closest to what you want, then override the difference with a one-off CLI run when needed. If you need a combination that’s not in the preset list, tell us on Discord.

For developers / add-on authors

The preset → allowed-stages map is exposed as a static method:

$presets = SuperSpeedyImports_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 superspeedyimports_filter_stages_to_run filter at priority 5. The preset callback is not added when a CLI run names its own stages, so a filter at priority 4 or 7 still runs on such a run but sees every registered stage rather than the preset’s cut. Your add-on can:

// Override a preset entirely or add a new one
add_filter('superspeedyimports_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 modes and what each stage writes – the per-stage account of what each mode writes for new and existing items.
• import-template-abstract.php:getStagePresets() – the canonical preset → stages map.
• import-template-abstract.php:getFilteredStagesWithParallelInfo() – where the mode filter is installed at priority 5, for every runner (skipped when a CLI run names its own stages).

Written for Super Speedy Imports 3.40.0.