Replace Product-Category Assignments During Magento CSV Import
When a product CSV is meant to describe each product's complete category membership, adding new links is only half the job. You must also remove old links that no longer belong. Import Category Replace adds a category-handling setting to Magento's native product-import workflow so a non-empty categories cell can define the final assignment set.
Its current direct-store version is 1.0.3. This is product-assignment maintenance, not an import of category names, descriptions or parent relationships. Use category-record management for those supported record fields, and Magento's category editor for an existing parent move.
Why categories can accumulate after Add/Update
In the native additive product-category workflow described by the module guide, importing a new category does not remove an existing assignment simply because you omitted it. A product that belonged to “Old Range” can therefore remain there after “New Range” is added.
First inspect your actual importer and saved links. Native product import, a supplier connector and a third-party importer may take different routes. A historical report of additive categories does not establish the behaviour of every current integration.
Magento's whole-product Replace behaviour is a different operation from replacing category assignments. Do not select it merely because its label includes “Replace”. For a few products, editing category assignments in Admin may be sufficient. For a selected grid batch, Bulk Product Operations offers separate assign, remove and replace actions.
Make the intended file authoritative
Under Stores → Configuration → AgenticEcom · Catalog → Product Import Settings → Category Handling, select Category Import Behaviour: Replace. Append retains the normal additive behaviour. Save the setting and check it before running an unrelated scheduled import: this is a configuration choice affecting the relevant native import route, not just a label on one spreadsheet.
Prepare the usual product CSV using the standard category paths, such as Default Category/Inspection/New Range. In Replace mode, a row with a non-empty categories value sets the product's assignments to the resolved categories in that cell. Include every category you want retained, not merely the new additions.
Illustrative staging example: one moved product and two controls
This example has not been executed for this article. Create disposable products and category paths in staging; record their existing memberships before importing.
| Product | Before import | CSV instruction | Result to verify in Replace mode |
|---|---|---|---|
| TEST-01 | Old Range and Clearance | New Range only | New Range only; both omitted links removed. |
| TEST-02 | Old Range | Blank categories cell | Old Range remains; a blank is not a clear-all instruction. |
| TEST-03 | Old Range | No imported row | Unchanged. |
- Back up the staging database and retain the product export. Confirm that the intended category tree exists and that each path is spelled correctly.
- Use System → Data Transfer → Import with Products and the intended native import behaviour. Keep this category setting distinct from whole-product Replace.
- Read validation and import results, then reopen all three products and inspect their category selections.
- Check the old and new category pages, navigation and product counts after the relevant indexing and cache updates.
- If you also use a CLI or scheduled integration, run a separate small qualification through that actual route before a production batch.
A blank cell does not remove every category
The module leaves assignments unchanged for empty category cells. The guide also describes skipping a value that resolves to no valid category rather than clearing everything. These guards are useful for imports carrying no category data; they do not turn an incomplete but valid non-empty list into a safe instruction. A cell containing just one valid category can still remove other memberships in Replace mode.
Review supplier files accordingly. An “only changed categories” feed is not a complete assignment list. If the supplier cannot provide the final set, retain append behaviour or transform and review the data before using replacement.
What this does not change
The module changes category-link handling within the relevant product import. Other product columns still follow that import's normal behaviour. It does not edit category records, move existing categories or supply a general undo. Keep a database recovery route and verify any price, stock or attribute columns carried alongside the category data.
The public product identifies Magento Open Source 2.4.9 as its target. Check the exact package and PHP requirements and test your import route; this article supplies no new runtime test or universal third-party-importer compatibility claim.
Review Import Category Replace, its configuration guide and Adobe's native import behaviours before making a live file authoritative.
This article describes AgenticEcom's own module. Reviewed for accuracy on 4 November 2026.
Product information reviewed 4 November 2026 by AgenticEcom. Illustrative examples are not customer results or new runtime tests.