- A supplier sends a product that looks vaguely like several items already in the marketplace taxonomy.
- Its name points towards one category.
- For buyers, a forced match creates irrelevant search results.
- On a supplier-driven Medusa marketplace, we treated UNCATEGORIZED as a legitimate business outcome rather than an automation failure.
The client problem
A supplier sends a product that looks vaguely like several items already in the marketplace taxonomy.
Its name points towards one category. Its description suggests another. One technical specification contradicts both. A categorisation model can still return the nearest available category, but “nearest” is not the same as “correct”.
For buyers, a forced match creates irrelevant search results. For suppliers, it makes products harder to review. For the marketplace, it quietly damages the taxonomy that navigation, procurement reporting and product discovery depend on.
On a supplier-driven Medusa marketplace, we treated UNCATEGORIZED as a legitimate business outcome rather than an automation failure. The pipeline searches valid leaf categories, asks whether any candidate is genuinely coherent with the product, records why it declines, and leaves a fast manual path for operators. The taxonomy can then evolve without pretending that every product already has a home.
The client problem: a complete catalogue can still be wrong
Marketplace teams naturally want every product categorised. A category powers navigation, filters, search relevance, product specifications and reporting. An empty category looks like unfinished work.
That pressure encourages a dangerous shortcut: always choose the closest category.
Imagine a replacement component whose title mentions a pump, whose description discusses a control assembly and whose specifications list a voltage incompatible with the candidate equipment. Assigning it to “Pumps” may make the completion dashboard greener, but it tells buyers something the source data does not support.
There are at least three different situations hiding behind an empty category:
- the product data is coherent, but the taxonomy has no suitable leaf;
- the source fields contradict one another and need correction;
- a suitable category exists, but retrieval or manual review has not found it yet.
Those situations need different responses. One asks for taxonomy work, one asks for supplier-data work, and one asks for better discovery. A generic fallback category cannot express the difference.
Search for candidates before asking for a decision
We did not ask an AI model to memorise or invent the marketplace taxonomy.
The categorisation service first builds a compact product query from the name, a bounded description, the existing supplier category and a small number of meaningful specifications. Part numbers, compatibility lists and other noisy identifiers are excluded from the semantic signal where they would overwhelm product meaning.
Elasticsearch then retrieves a controlled set of category candidates. The query combines keyword and semantic fields, but filters the results to leaf categories. The model receives those candidate IDs, names, paths and descriptions.
This changes the task from “name any plausible category” to “decide whether one of these real choices fits”. It also keeps the taxonomy itself authoritative. The model helps interpret a product; it does not create catalogue structure by improvisation.
When search is unavailable or returns no candidates, the safe result is not a fabricated ID. It is UNCATEGORIZED.
Let the classifier say “none of these”
The model output contract includes one special value alongside the candidate IDs: UNCATEGORIZED.
The prompt asks for a strong, logical match based on function, product description and technical characteristics. If a candidate conflicts with those signals, the model must decline rather than optimise for completion.
The parser converts that decline into a null category instead of a synthetic “Miscellaneous” node. It preserves confidence, reasoning and discrepancy information with the product's import metadata.
The ingestion step also verifies positive answers. If the model returns a category that was not in the retrieved candidate set, the result is treated as invalid and no relationship is created.
That closed-world validation protects the catalogue from malformed output and from IDs that may have disappeared between retrieval and ingestion. A language model's response is a proposal inside a contract, not authority to write arbitrary relationships.
Distinguish bad source data from a missing category
An uncategorised result becomes much more useful when it explains what happened.
The pipeline asks the classifier to separate two broad decline reasons. data_conflict means the product's own name, description or specifications contradict one another. no_match means the product description is coherent, but none of the available candidates fits.
Both outcomes leave the product without a forced category, but the next action differs:
- a data conflict should return to supplier-data review;
- a no-match result may reveal a retrieval issue or a genuine taxonomy gap.
The stored discrepancy names the conflicting field or explains the mismatch. The dashboard can therefore show more than a count of failed classifications.
This is where honest automation creates operational value. Refusal is not the end of the workflow. It routes the product to the team best placed to resolve the uncertainty.
Keep the product visible to operations, not falsely visible to buyers
An unresolved product still needs a lifecycle.
The system records the categorisation outcome and its reason. Products with a valid candidate can progress towards proposal and review. Products without a defensible category remain explicitly identifiable as uncategorised or conflicted instead of inheriting a broad public category.
This preserves two truths at once: the supplier row exists, and the marketplace is not yet ready to present it as correctly classified.
That distinction is especially important in large catalogues. Hiding uncertain products by deleting them loses supplier effort and makes remediation difficult. Publishing them under an invented category damages buyer trust. A durable unresolved state gives operations a queue they can improve.
“Uncategorized” is therefore not a merchandising destination. It is an honest workflow state with evidence and a next action.
Make manual correction fast enough to be used
Automation does not remove the need for catalogue expertise. It should make expert attention more effective.
We added category editing directly to the admin product list. An operator can open a compact picker from the category cell, browse the hierarchy level by level or search by category name. Search results display the full path so repeated names remain understandable.
Top-level nodes lead deeper into the tree and cannot be selected. Leaf selection updates the cell optimistically, calls the dedicated assignment endpoint and then replaces the optimistic value with the canonical relationship returned by Medusa. If the request fails, the previous value is restored and the operator sees a clear error.
The list and product detail queries are invalidated after success. The correction therefore appears consistently without requiring the operator to open the full product-edit form.
This is not merely interface polish. If resolving one product requires navigating several pages, uncertain categories accumulate. Reducing the correction to a guarded action inside the review surface makes quality work part of normal operations.
Replace the assignment through Medusa's workflow
The category endpoint does not patch a join table from the browser.
It validates the request, resolves the category through the Medusa graph, enforces the non-root rule and runs Medusa's product update workflow with exactly one category ID. It then reads the product and its category relationship back from the canonical graph.
This gives the interface a narrow business operation: replace this product's category with this valid leaf.
The operation is deliberately simpler than the complete product editor. It does not ask the client to send a partially loaded product object or reconstruct fields it never intended to change. That reduces the risk that a quick taxonomy correction overwrites unrelated product data.
When extending an admin, small purpose-built commands are often safer than reusing a broad update form for every operational action.
Evolve the taxonomy without rewriting its history accidentally
Taxonomies change as the marketplace learns.
New categories appear. Existing categories move under better parents. Names and descriptions become clearer. Some branches disappear because they were redundant or misleading.
The project includes a reviewed, in-place taxonomy migration rather than a destructive wipe. New nodes are added shallow-first so their parents exist. Existing nodes are moved and updated while preserving their IDs and product links wherever possible.
Deletion is treated differently. Before a removed category is deleted, its linked products are set back to draft and unlinked. They become unresolved work instead of being silently reassigned to the nearest surviving branch.
That choice protects meaning. If the business removes a category, it has not automatically decided where every former product belongs. Recategorisation deserves a new decision based on the new taxonomy.
Preserving IDs during moves also prevents a structural edit from looking like a completely new business identity to every downstream consumer.
Use uncategorised products as feedback, not as a dumping ground
Once decline reasons are explicit, the unresolved queue becomes a source of product intelligence.
A cluster of no_match products with coherent descriptions may show that the taxonomy lacks an important commercial branch. Repeated data_conflict outcomes may identify a supplier mapping problem. Invalid candidate IDs may reveal a stale search projection or a category changed during a long-running batch.
Those signals should inform taxonomy and import work, but they should not automatically create categories. A category affects navigation, merchandising, specifications and reporting; it needs deliberate ownership.
The platform makes the evidence visible so the team can decide. It does not convert every exception into permanent structure.
This prevents the familiar “Other” category from becoming a graveyard that nobody can analyse and every integration learns to ignore.
A practical taxonomy integrity checklist
Before automating product categorisation, ask:
- Does retrieval search the current canonical taxonomy?
- Are only assignable leaf categories proposed?
- Does the model receive a closed list of valid IDs?
- Can it explicitly decline all candidates?
- Is a returned ID checked against the retrieved set?
- Are contradictory product data and taxonomy gaps separate outcomes?
- Is the reason for refusal stored with the product?
- Can operators find unresolved products later?
- Can they browse and search categories without opening the full editor?
- Does the server reject root assignments independently of the UI?
- Does a quick correction update only the category relationship?
- Are failed optimistic changes rolled back visibly?
- Do taxonomy moves preserve stable category identities?
- Are products unlinked and reviewed before a category is removed?
- Does the business learn from unresolved clusters without creating categories automatically?
The aim is not a dashboard that says 100% categorised. It is a catalogue whose categories still mean something.
The broader lesson
Medusa provides the product and category foundations. The client's marketplace needed an operational contract for uncertainty that the commerce engine could not define on its behalf.
We built that contract around constrained candidates, assignable leaves, explicit refusal, reasoned outcomes, guarded manual correction and in-place taxonomy evolution.
The result is a system that can automate the easy decisions without lying about the difficult ones. Buyers are not sent through irrelevant branches merely to satisfy a completeness metric. Suppliers receive clearer remediation paths. Catalogue teams can improve both the data and the taxonomy from evidence.
Sometimes the most valuable answer an automated commerce system can give is: none of the available categories is correct yet.
That is not unfinished architecture. It is the beginning of a trustworthy decision.