Vendor Categories

Every distributor ships its own merchandising hierarchy alongside its products, and it is never your hierarchy. Category mapping is where you tell ILLUMA which of your categories each of their groups points at, so products coming in from the feed land on the right shelf instead of nowhere.

How the two trees relate

A Product Catalog feed can carry the vendor’s category levels — Ace’s article feed, for example, carries department → merchandise class → product group. When a run reads the file it discovers that tree and records every node it saw, with a count of how many rows in the file sat under it.

Discovery never files anything. It only builds the list you then make decisions against.

Three things are worth understanding before you start mapping:

• The vendor’s tree is navigation, not structure. Where a group sits in the vendor’s hierarchy says nothing about where it belongs in yours. Several of their groups may collapse into one of your categories, and some may have no home at all. Every group maps freely to any category you have.
• You map at the deepest level. The mapping screen shows the deepest level present in that vendor’s tree — the groups, not the departments. Parents ride along as a grey context line under each name.
• Identity is the full code path, not the code. Vendor group codes are often child indexes (04 means “the fourth group under this class”), so the same code appears under unrelated branches. ILLUMA keys each node on its whole chain of codes (1/105/04), which is why your decisions survive every subsequent file.

ℹ️ Note: This is a different screen from Category Routing, which sits on the vendor’s Integration tab under the purchase-order submission settings. That one maps your categories to vendor keywords for the Freshdesk subject line so their support desk routes the ticket. This one decides where imported products get filed. See Sending Purchase Orders for the routing one.

Before you start

Two things have to exist first.

1. Your own category tree — go to Categories and build it. There is nothing to map to otherwise, and both the picker and the suggestion engine will tell you so in as many words.
2. A Product Catalog feed that knows which columns carry the hierarchy — see the next section. A feed with no category levels configured brings no tree in, and the mapping screen stays empty.

Tell the feed which columns carry the hierarchy

Category levels are configured per feed, and only on Product Catalog feeds. An Inventory feed updates stock on products that are already linked, so it has no hierarchy to read and no Categories section.

1. Open the feed — go to Purchasing → Vendors → open the vendor → the Integration tab → the Products panel, then on the feed row click the ⋯ menu and choose Edit feed.
2. Scroll to Categories — the section sits between Which items to import and Fulfillment.
3. Add one level per tier, broadest first — click + Add level and pick the code column and the name column for that tier. If ILLUMA has already read a sample of the vendor’s file, both are dropdowns of the real column names; otherwise they are free-text boxes you type the header into.
4. Save the feed — then run it. The tree appears once a run has read the file.

Field	What it is
Code column	The column holding that level’s code. This is the stable identity — the thing that does not change when the vendor rewords a label. A level with no code column selected is dropped when you save.
Name column	The column holding that level’s human-readable label. This is what you read on the mapping screen. Optional: a level with a code and no name still builds, and the node shows its code.

⚠️ Warning: Levels must be listed outermost first, and a level whose code column is missing from the file stops the chain there — every level below it is dropped rather than built with a hole in it. If you configured three levels and only see two on the mapping screen, check the third level’s code column name against the file.

ℹ️ Note: A Product Catalog run stages every decision in the review queue and writes nothing to your catalog — but it still records the vendor’s tree. Discovering what a vendor sells is not a change to your catalog, and the mapping screen has nothing to show until the tree exists.

After a run, the feed row’s stat grid shows a vendor categories figure (“found in their hierarchy”) — that is every node discovered across all levels, not just the ones you map, and not just the level you see on the mapping screen.

📷 Screenshot: The Edit Feed modal scrolled to the Categories section, showing three configured levels each with a code-column and name-column dropdown, plus the “+ Add level” button. (placeholder — replace with /docs-images/vendors/vendor-categories-feed-levels.png)

One tree per vendor, not per feed

A vendor can carry as many Product Catalog feeds as it has files — an item master, an enrichment feed, a spreadsheet you upload by hand — and every one of them discovers into the same vendor tree. Category levels are configured on each feed separately, but the nodes they produce all land in one place, and the mapping screen you reach from any of those feed rows is the same screen.

That is usually what you want: map once, and every feed on that vendor files by the same rules. Two things follow from it.

• Configure the levels consistently. The screen shows the deepest level present anywhere in the vendor’s tree. If one feed defines three levels and another defines two, the two-level feed’s leaves are level 2 — parents, as far as the screen is concerned — and they never appear as mappable rows. Either give both feeds the same levels, or leave the Categories section empty on the second feed and let the item master own the hierarchy.
• Item counts belong to the last run that touched the node. A node’s count is rewritten by whichever of the vendor’s feeds ran most recently over it, so read it as “how big this group is”, not as an audit of a specific file.

Open the mapping screen

Purchasing → Vendors → open the vendor → the Integration tab → the Products panel → the Product Catalog feed’s ⋯ menu → Category mapping. The page lives at /dashboard/dealer/vendors/<vendor>/categories.

The header shows the vendor’s name as a back link, the title Category mapping, and a Suggest matches button on the right. Below that is a toolbar with a search box, an Unmapped only checkbox, and a running count — “X of Y mapped”.

The table lists the deepest level of the vendor’s tree, biggest first, 100 rows to a page. Sorting by item count is deliberate: most groups hold three or four products and a handful hold hundreds, so the first page or two is usually the difference between mapping everything that matters and mapping everything.

Column	What it shows
Vendor group	The vendor’s label for the node, with its parent chain underneath in small grey type — context only.
Your category	The full path of the category it points at (e.g. Outdoor › Lawn Care › Trimmers), or Not mapped, or Not imported for a skipped node, or a Suggested row you can click to accept.
Items	How many rows in the vendor’s file sat under this node in the last run that read it.
(actions)	Map / Change, and Skip or Remove.

A row you have mapped is tinted, so you can see progress down the page at a glance. A skipped row is not tinted — it reads Not imported instead.

📷 Screenshot: The Category mapping screen with the toolbar (search, “Unmapped only”, “X of Y mapped” counter) and a table showing a mix of mapped rows (tinted, full category path), a “Suggested” row with its percentage, and unmapped rows. (placeholder — replace with /docs-images/vendors/vendor-categories-mapping-screen.png)

Map a group to one of your categories

1. Click Map on the row — a modal opens titled Map “<group name>”.
2. Search your categories — the box is focused for you. Type any part of the path; matching is on the whole path, so lawn finds Outdoor › Lawn Care as well as Lawn Care › Mowers.
3. Click the category you want — the mapping saves immediately and the table reloads.

Categories are listed as full paths rather than leaf names, because plenty of catalogs have three categories called “Accessories” and the leaf name alone cannot tell them apart. The list shows the first 50 matches, so narrow the search rather than scrolling. Every one of your categories is offered here, active or not.

Button	What it does
Map	Opens the picker for a node with no decision on it yet.
Change	Same picker, for a node that is already mapped. Repointing it is one click.
Skip	Marks the branch as one you do not want imported. Shown on rows that are not yet decided.
Remove	Clears the decision — mapped or skipped — and puts the node back in the undecided pile.

Every decision is stamped with the dealer account that made it and the time it was made. Clearing a decision with Remove clears that stamp too, so an undecided node is genuinely undecided again — including to the matcher.

📷 Screenshot: The “Map …” modal open, showing the search box with a partial query and the list of matching category full paths below it, separated by ›. (placeholder — replace with /docs-images/vendors/vendor-categories-map-picker.png)

Skip branches you do not carry

Most vendors sell things you do not. Skip records that as a real decision rather than leaving the row looking like unfinished work.

A skipped node:

• shows Not imported in the Your category column,
• counts toward the “X of Y mapped” progress figure — the counter measures decided, not mapped,
• drops out of the Unmapped only filter,
• is left alone by Suggest matches, and never shows a suggestion, and
• carries no target, so nothing under it is filed into one of your categories.

Remove undoes it.

💡 Tip: Working biggest-first and skipping aggressively is usually the fastest way to a clean screen. A vendor’s long tail of tiny groups rarely needs individual attention.

ℹ️ Note: Skipping a category branch is not the same as excluding those rows from the import. The rows still come in, still match, and still stage for review — they simply arrive with no category. If you want them out of the import altogether, use the feed’s Which items to import rules instead; see Product Feeds.

Suggest matches

Thousands of decisions is not a form anyone fills in, so ILLUMA will propose targets for you. Click Suggest matches in the page header; the button reads Matching… while it works.

Suggestion goes on names, and only names. It cannot reason structurally — you organise your catalog your own way, so “this sits under the vendor’s Plumbing” tells it nothing about where it belongs in yours. What it does:

• normalises both names to comparable words — strips punctuation, lowercases, crudely singularises (cleaners → cleaner), and drops one-letter words plus the fillers and, the, for, with, misc, other;
• takes an exact normalised-name match at 100% confidence;
• otherwise scores every one of your categories on shared words versus the combined vocabulary of both names, so a long name matching a short one on a single common word does not come back looking confident (PAINT BRUSHES should not match Paint at full strength);
• discards anything below 34% — a plausible-looking wrong answer gets approved, an empty one gets read.

When it finishes you get a summary: “N suggested, M had nothing close enough. Nothing was mapped — click a suggestion to accept it.”

⚠️ Warning: A suggestion is an opinion, not a mapping. Nothing is filed anywhere until you accept it. Accept one by clicking the suggested row itself — the line tagged SUGGESTED with the category path and a confidence percentage.

A few behaviours worth knowing:

• It scores against your category’s own name, not its full path. A category called Trimmers is matched on the word trimmers, whatever it sits under. The path is shown to you on the row so you can see where accepting it would actually file things.
• It never overwrites a human decision. Only undecided nodes are considered, so anything you mapped or skipped is untouched, however confident the matcher is.
• It only proposes against active categories. An inactive category can still be chosen by hand in the picker, but it will never be suggested.
• The count can exceed what you see. Suggestion runs across every undecided node in the vendor’s tree, including the parent levels the screen does not display. Those parent suggestions are real and still count toward “N suggested” — you just cannot accept them from this table.
• Re-running is safe and useful. After you have built out more of your own tree, run it again — still-undecided nodes get freshly scored suggestions, replacing whatever the previous pass proposed.

📷 Screenshot: Close-up of a suggested row: the orange “SUGGESTED” tag, the proposed category path, and the confidence percentage in grey, with the cursor over it. (placeholder — replace with /docs-images/vendors/vendor-categories-suggestion-row.png)

Finding the work that is left

Control	Behaviour
Search box	Filters on the vendor’s group name only — not the parent chain, and not the category it points at. Case-insensitive, matches anywhere in the name. Press Enter or click Search.
Unmapped only	Hides everything you have mapped or skipped. What is left is the actual worklist.
“X of Y mapped”	Always the whole vendor’s totals for the deepest level, regardless of what the filters are showing. Skipped nodes count as done.
Previous / Next	100 rows per page, biggest first. Filtering happens before paging, so a search narrows the pages rather than the current one.

If the table is empty, the message tells you which case you are in: nothing matched the search, everything is mapped, or no tree has been discovered yet — in which case run the vendor’s Product Catalog feed and it will bring their groups in.

How a product actually gets filed

Mapping alone changes nothing. Here is the full chain.

1. The feed run stages rows. For each row it records that row’s node as a code path — the deepest complete chain of codes on that line. A blank level stops the walk, so a row with a department but no group is recorded at the department.
2. You map the tree on this screen.
3. You create or apply from Catalog review. That is the moment products get filed. See The Review Queue.

Action on Catalog review	What gets filed
Create all … new products	Each product filed as it is minted, into the category mapped for its node. This runs as a background job.
Apply … matches to catalog	Products you already had, newly linked to this vendor, filed the same way. Existing category links are deduplicated first, so re-applying does not double up.

Filing walks up the vendor’s own tree from the row’s node until it finds a node you mapped, so an undecided group can still land correctly if a level above it has a mapping. If nothing on the way up is mapped, the product is simply not filed — no default, no guess.

Filing is always additive and never primary: it adds a category to the product, it never removes one and never displaces the product’s primary category. That is why it is not governed by the feed’s Updating products you already have policy — adding a shelf takes nothing away.

The result line after applying names it directly — “N filed into categories”. The create job does its filing silently as it mints each product; the proof is on the products themselves.

⚠️ Warning: Changing a mapping changes where future imports file things. It never re-files what already landed, and neither the mapping screen nor Catalog review has a control that will. Repointing a group after you have created 2,000 products under it leaves those 2,000 where they were — you would correct them on each product’s own page, or ask ILLUMA support for a bulk backfill.

💡 Tip: Map first, create second. Run the feed once to discover the tree, do your mapping, then create products from the review queue. Mapping afterwards is a much bigger cleanup.

ℹ️ Note: Rows for products already linked to this vendor do not pass through Catalog review again — a later run refreshes their cost and content directly and files no categories. This is the other half of why the order matters: once a product is linked, running the feed again will not shelve it.

Protecting a product you have filed by hand

On a product’s edit page, under Protect from vendor updates, ticking Categories stops vendor feeds filing that product into anything. Because filing is additive-only, protect here can only mean don’t file — there is no “fill a blank” middle ground for this one aspect, the way there is for a title or a description. Products with it ticked are skipped entirely when matches are applied.

What a re-run does

The tree is upserted, never replaced.

• Nodes you already decided on keep their decision. Only the item count and the name can move.
• New nodes arrive undecided, so a vendor adding a group shows up as new work rather than silently vanishing into the wrong place.
• Nodes that stop appearing in the file are left in place, not deleted. A vendor dropping a group from one drop should not discard the decision a human made for it. Their item count simply stops changing.
• A node whose label was blank on the first file picks up a name as soon as any later row carries one. A code with no label anywhere shows the code itself, so the row is at least identifiable.
• A node whose count and name are both unchanged is not rewritten at all — which is why a daily feed against a stable hierarchy costs nothing.

Next

Build out the tree you are mapping to in Categories, work the decisions the feed stages in The Review Queue, and see how a filed product presents in Products. If a run brought in no tree at all, Troubleshooting Vendor Feeds covers reading a run’s tallies.