<p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fbqo8jor205ea7hhg8rj8.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fbqo8jor205ea7hhg8rj8.png" alt="Normalized Categories on PSRESTful — one cross-supplier category tree for promotional products" width="800" height="512"></a></p> <p>If you've ever tried to search "polos under $10 in navy" across more than one supplier, you already know the punchline. SanMar files them under one label, S&amp;S Activewear under another, Hit Promotional<br><br> under a third, and a long tail of suppliers keep their own taxonomy of taxonomies — <code>Polos</code>, <code>Knits</code>, <code>Apparel &gt; Tops &gt; Sport Shirts</code>, <code>POLO/SPORT</code>, <code>Performance Polos</code>, you get the idea. Same garment, <br> twelve different category strings. </p> <p>We just shipped a fix: a single curated category tree, an AI classifier that fills it in, and a real <code>normalized_category_id</code> filter on the API. PSRESTful Product Search and<br><br> <a href="https://apps.shopify.com/promosync" rel="noopener noreferrer">PromoSync</a> Product Search both use it as of today.</p> <h2> The Problem </h2> <p>PromoStandards never standardized categories. The Product Data service hands back whatever the supplier decides to put in <code>ProductCategory</code> and <code>ProductSubcategory</code>, and every supplier decides differently. That's fine for browsing one supplier — it falls apart the moment you try to search across all of them.</p> <p>Concretely, when a sales rep is on the phone and asks "what polos do we have under $10 in navy that ship from the East Coast?", the honest answer used to be "give me a few minutes." You'd run the search per supplier, mentally translate each supplier's category labels, and stitch the results back together.</p> <p>We wanted a single dropdown that says <strong>Polos</strong> and means it. </p> <h2> A Curated Two-Level Taxonomy </h2> <p>The taxonomy lives in our Django backend as a YAML fixture and a pair of models — <code>NormalizedCategory</code> and <code>NormalizedSubcategory</code> — plus a nullable <code>normalized_subcategory_id</code> foreign key on <code>Product</code>.<br> Eleven top-level categories, ~50 subcategories, deliberately small:</p> <ul> <li> <strong>Apparel</strong> — T-Shirts, Polos, Crewnecks, Hoodies, Fleece, 1/4 Zip, 1/2 Zip, Jackets, Vests, Pants, Shorts, Activewear, Scarves </li> <li> <strong>Headwear</strong> — Caps, Beanies, Visors, Bucket Hats</li> <li> <strong>Bags</strong> — Backpacks, Totes, Duffels, Coolers, Drawstrings </li> <li> <strong>Drinkware</strong> — Tumblers, Mugs, Water Bottles, Stemware </li> <li> <strong>Tech</strong> — Power Banks, Chargers, Audio, Cables &amp; Adapters, Phone Accessories, Projectors </li> <li> <strong>Office &amp; Writing</strong> — Pens, Notebooks, Desk Accessories, Calendars </li> <li> <strong>Outdoor &amp; Lifestyle</strong> — Blankets, Umbrellas, Camping, Towels, Sunglasses </li> <li> <strong>Novelties</strong> — Stress Relievers, Fidget Toys, Plush Toys </li> <li> <strong>Awards &amp; Recognition</strong> — Trophies, Plaques, Crystal, Medals, Ribbons, Globes </li> <li> <strong>Trade Show &amp; Signage</strong> — Banners, Flags, Pennants, Table Covers, Signage </li> <li> <strong>Personal Care</strong> — Hand Sanitizer, Sunscreen, Lip Balm, Masks </li> </ul> <p>Two design choices worth calling out: </p> <ol> <li> <strong>Two levels, not five.</strong> Distributors don't navigate ten-level decision trees on the phone. Category → Subcategory is the deepest you ever need to go for a search filter. </li> <li> <strong>Slugs are the contract, names are not.</strong> Each category and subcategory has a stable <code>slug</code> (<code>polos</code>, <code>power-banks</code>) and an admin-editable <code>name</code>. The filter API takes ids; URLs use slugs. Renaming "Tech" to "Electronics" tomorrow doesn't break anything downstream. </li> </ol> <h2> Classifying Existing Products with LLMs </h2> <p>Curating a tree is the easy part. We had hundreds of thousands of existing products to classify, and "go through them by hand" was never on the table. </p> <p>So we built an LLM-backed classifier. For each product, the model returns a single best subcategory along with a confidence score and a one-line reasoning. The classifier is pluggable — we run it against a hosted model in production, and against a local model via Ollama for backfills and for environments without API access. Same input, same output shape, swap the backend.</p> <h2> API: <code>GET /extra/v2/normalized-categories</code> </h2> <p>The taxonomy is exposed as a first-class endpoint on the PSRESTful API. The whole tree fits in one paginated response — categories with their active subcategories nested inline:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code> curl <span class="s1">'https://api.psrestful.com/extra/v2/normalized-categories?is_active=true'</span> <span class="se">\</span> <span class="nt">-H</span> <span class="s1">'x-api-key: YOUR_KEY'</span> <span class="se">\ </span> <span class="nt">-H</span> <span class="s1">'accept: application/json'</span> <span class="o">{</span> <span class="s2">"count"</span>: 11, <span class="s2">"page"</span>: 1, <span class="s2">"page_size"</span>: 50, <span class="s2">"total_pages"</span>: 1, <span class="s2">"next"</span>: null, <span class="s2">"previous"</span>: null, <span class="s2">"results"</span>: <span class="o">[</span> <span class="o">{</span> <span class="s2">"id"</span>: 1, <span class="s2">"name"</span>: <span class="s2">"Apparel"</span>, <span class="s2">"slug"</span>: <span class="s2">"apparel"</span>, <span class="s2">"sort_order"</span>: 0, <span class="s2">"is_active"</span>: <span class="nb">true</span>, <span class="s2">"subcategories"</span>: <span class="o">[</span> <span class="o">{</span><span class="s2">"id"</span>: 10, <span class="s2">"name"</span>: <span class="s2">"T-Shirts"</span>, <span class="s2">"slug"</span>: <span class="s2">"t-shirts"</span>, <span class="s2">"sort_order"</span>: 0, <span class="s2">"is_active"</span>: <span class="nb">true</span><span class="o">}</span>, <span class="o">{</span><span class="s2">"id"</span>: 11, <span class="s2">"name"</span>: <span class="s2">"Polos"</span>, <span class="s2">"slug"</span>: <span class="s2">"polos"</span>, <span class="s2">"sort_order"</span>: 1, <span class="s2">"is_active"</span>: <span class="nb">true</span><span class="o">}</span> <span class="o">]</span> <span class="o">}</span> <span class="o">]</span> <span class="o">}</span> </code></pre> </div> <p>Two things to notice: </p> <ul> <li>One call, full subtree. The taxonomy is small enough that we deliberately denormalize the response. No second ?parent= call to flesh out the children. </li> <li>is_active=true filters both levels. It returns only active categories and drops inactive subcategories from each subcategories array. So a "soft delete" of a subcategory propagates cleanly to clients without breaking the filter the next time around. </li> </ul> <p>This is not the existing GET /extra/v2/categories endpoint, which still returns the raw, supplier-specific category strings. The two coexist on purpose — supplier categories are still useful for<br><br> supplier-scoped browsing, and the normalized taxonomy is the cross-supplier one.</p> <h2> Filtering Products </h2> <p>Two new query params on GET /extra/v2/products: </p> <p>GET /extra/v2/products?normalized_subcategory_id=11 # Polos, exact match<br><br> GET /extra/v2/products?normalized_category_id=1 # anything under Apparel<br><br> GET /extra/v2/products?normalized_category_id=1&amp;normalized_subcategory_id=11<br><br> <strong>subcategory wins</strong> </p> <p>The normalized_category_id filter is implemented as a SQLAlchemy subquery — it expands to "subcategories whose parent is this category id," then filters products against that set. So a single category<br><br> id matches every leaf under it without the client having to expand the tree itself. When both are passed, the more specific id wins; this matches how cascading dropdowns send their state and means<br> clients don't have to clear the parent when the child changes. </p> <p>Each product in the response now also carries a normalized_subcategory block when classified:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight json"><code><span class="p">{</span><span class="w"> </span><span class="nl">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">12345</span><span class="p">,</span><span class="w"> </span><span class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Performance Polo"</span><span class="p">,</span><span class="w"> </span><span class="nl">"main_category"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Polos"</span><span class="p">,</span><span class="w"> </span><span class="nl">"normalized_subcategory"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">11</span><span class="p">,</span><span class="w"> </span><span class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Polos"</span><span class="p">,</span><span class="w"> </span><span class="nl">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"polos"</span><span class="p">,</span><span class="w"> </span><span class="nl">"category"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nl">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nl">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Apparel"</span><span class="p">,</span><span class="w"> </span><span class="nl">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"apparel"</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre> </div> <p>Clients get the leaf, the parent, and the slugs in one trip — no second lookup against the taxonomy endpoint to render a label. </p> <h2> Wired Into PSRESTful Product Search </h2> <p>Inside <a href="https://psrestful.com/extra/search/products" rel="noopener noreferrer">https://psrestful.com/extra/search/products</a>, the new "By Category" filter is a single dropdown over the active subcategories, grouped under their parent category. Pick "Polos" once, the search<br><br> runs across every supplier you have credentials for, and the supplier-specific category strings stay out of your way.</p> <p>If a product hasn't been classified yet, the search result card falls back to the supplier's main_category so the row still says something useful. As the classifier sweeps newer products, the normalized subcategory takes over.</p> <h2> Wired Into PromoSync Product Search </h2> <p><a href="https://apps.shopify.com/promosync" rel="noopener noreferrer">https://apps.shopify.com/promosync</a> hits the same endpoint from the Shopify app side, but with a couple of small wrinkles worth flagging because they came up in code review: </p> <ul> <li>Two-step cascade, HTMX-driven. Picking a category triggers an hx-get against a server-rendered subcategory . The payload only forwards the more specific id (subcategory if set, otherwise the parent category), which keeps the URL clean and matches the API's "subcategory wins" rule.</li> <li>Per-shop 6-hour cache. PromoSync caches the full taxonomy per shop because every search page render needs it. Six hours is plenty — the taxonomy moves at the speed of YAML edits. </li> <li>Read ids from raw query data, not the form. Django form fields validate against the queryset they were built with at request time. If the cached taxonomy is one revision behind the database, the form would silently drop the filter on submit — the dropdown would show the choice, but the search would ignore it. We mirror our brand-filter pattern instead: pull the id directly out of request.GET for the actual query, and use the form only for rendering. Fewer surprises. </li> </ul> <h2> Why This Matters </h2> <p>Three things, in order of how much your team will feel them: </p> <ol> <li>Sales reps stop translating. "Polos" means polos. The supplier doesn't get to override that on the search page. </li> <li>Cross-supplier filtering is a single dropdown, not a join. The same category id works whether you have credentials for one supplier or fifty.</li> <li>AI classification is reproducible. The taxonomy is plain YAML, the classifier reads from the same database the API serves, and the suggestion queue means a low-confidence label gets a human look before it ships. No black-box magic — edit the tree, rerun the classifier, ship. </li> </ol> <p>If you're already on PSRESTful, the new "By Category" filter is live in <a href="https://psrestful.com/extra/search/products" rel="noopener noreferrer">https://psrestful.com/extra/search/products</a>. If you're integrating against the API directly, hit GET<br><br> /extra/v2/normalized-categories and start filtering products by normalized_category_id or normalized_subcategory_id — full schema is on <a href="https://docs.psrestful.com" rel="noopener noreferrer">https://docs.psrestful.com</a>. Not on PSRESTful yet?<br> <a href="https://psrestful.com/contact-us/" rel="noopener noreferrer">https://psrestful.com/contact-us/</a> and we'll get you set up. </p> <p>▎ Originally published on the <a href="https://blog.psrestful.com/posts/normalized-categories-cross-supplier-search" rel="noopener noreferrer">https://blog.psrestful.com/posts/normalized-categories-cross-supplier-search</a>.</p>