Import Category Replace

Magento’s product CSV import has a behaviour that catches everyone out: it appends categories. Import a product with categories and Magento adds them to whatever the product already has — and never removes the ones you left out. So when you re-categorise a catalogue, the import dutifully adds the new categories and leaves all the old ones in place, stranding every product in both. Import Category Replace adds the missing option: make the categories column authoritative, so the row defines a product’s complete, final category set.

It builds on native import

No new import screen to learn — this extends Magento’s standard product import. Same CSV, same workflow; you just flip one setting from Append to Replace.

Install

Install Import Category Replace with Composer using your AgenticEcom licence key (find it on your My Licences page — one key unlocks every module you own):

# 1. Register the AgenticEcom repository (once per store)
composer config repositories.agenticecom composer https://repo.agenticecom.net
composer config --global --auth http-basic.repo.agenticecom.net <YOUR-LICENCE-KEY> x

# 2. Require this module
composer require agenticecom/module-import-category-replace

# 3. Apply it
php bin/magento setup:upgrade && php bin/magento setup:di:compile && php bin/magento cache:flush

Have the whole platform?

Install every module in one command with composer require agenticecom/suite — see Install the complete suite.

Compatibility

Magento

Open Source 2.4.9 GA (and later 2.4.x).

PHP

Tested on 8.4 and 8.5.

Scope

Native CSV product import — admin and CLI (bin/magento).

Safe

Only category assignment changes — price, stock and attributes import as normal.

Append vs. Replace

Scenario	Native import (append)	With Replace turned on
Product in “Old Range”, CSV row says “New Range”	Ends up in both	Ends up in “New Range” only
Move 2,000 products to a new taxonomy	Hours of manual un-assigning	One import
A category not listed in a product’s row	Kept	Removed
A row with an empty categories cell	—	Left untouched (never wipes)
Price, stock, other attributes	Imported as normal	Imported as normal

Set it up

Flip the behaviour once in config, then every product import respects it.

Stores → Configuration → AgenticEcom · Catalog → Product Import Settings → Category Handling

1. Set Category Import Behaviour to Replace (the default is Append, which is native Magento). Save config.

2. Prepare your product CSV as usual, with the categories column holding the exact categories each product should belong to (Magento’s standard Default Category/Parent/Child path format).

3. Run the import normally — System → Data Transfer → Import, entity Products (or via CLI). Every row with a non-empty categories cell is set to exactly those categories; stale links are removed. Everything else imports as it always did.

Safe by default

A row with an empty categories cell is left untouched, so an import that carries no category data never wipes a product’s categories. A value that resolves to no valid category is skipped too, rather than clearing everything.

When you’ll want it

• Re-taxonomies — moving a catalogue to a new category structure.
• Re-platforms & migrations — making categories match a new source of truth in one pass.
• Supplier / PIM feeds — where a product’s categories should always mirror the feed, not accumulate over time.

FAQ

Does it change the CSV format?

No — same columns, same categories path format as native import. You just set the behaviour to Replace in config.

What happens to a category I don’t list for a product?

In Replace mode it’s removed from that product. The row defines the complete, final set of categories.

Could an import accidentally wipe all my categories?

No. Rows with an empty categories cell are skipped entirely, and a value that resolves to no valid category id is skipped too — so a partial import (price only, stock only) never touches category links.

Does it work from the CLI too?

Yes. It observes catalog_product_import_bunch_save_after in global scope, so it applies whether the import runs from the admin or bin/magento import commands.

Pairs well with…

Category Manager for shaping the tree and Bulk Product Operations for sweeping product changes.