- The model has finished. Thousands of products now have plausible categories.
- That shortcut confuses two very different decisions.
- Categorisation answers: where should this product sit in the catalogue?
- Price, imagery, supplier readiness, delivery, product copy and sales-channel placement can all matter after a category has been selected.
The client problem
The model has finished. Thousands of products now have plausible categories. The tempting next step is to make them live automatically.
That shortcut confuses two very different decisions.
Categorisation answers: where should this product sit in the catalogue? Publication answers: is the marketplace ready to make a commercial promise about this product to buyers?
Price, imagery, supplier readiness, delivery, product copy and sales-channel placement can all matter after a category has been selected. A valid AI decision is useful evidence, but it is not permission to sell.
For a large supplier catalogue built on Medusa, we separated those responsibilities in the product lifecycle. AI applies only validated category choices. Non-live products move to proposed. An administrator sees the proposed set and explicitly starts a tracked bulk-publication job. Only that operation moves the products into the buyer-facing state.
Automation prepares the release. A person still decides when the marketplace makes it.
The client problem: classification is not commercial readiness
A supplier import can contain far more than a taxonomy problem.
A product may have a category but no convincing image. Its description may be too sparse for a buyer to identify the correct specification. Its supplier may still be completing fulfilment setup. Its price may be present but not appropriate for the intended channel. An unresolved item may sit beside hundreds of well-classified products in the same batch.
If model ingestion publishes every successful category immediately, the catalogue becomes visible one response line at a time. There is no release moment, no proposed inventory to inspect and no clean way to say that the batch is prepared but not yet commercially approved.
We used Medusa's product status as that boundary. Classification enriches and proposes. Publication remains a separate command with its own actor, scope and operational result.
The distinction makes automation safer without discarding its speed.
Preserve the state of products that are already live
Not every product entering categorisation is new.
An existing published product may need its category repaired or enriched. Moving that product backwards to proposed simply because AI touched it would remove a legitimate live item from the marketplace.
The ingestion rule therefore distinguishes current lifecycle state. When a valid category is accepted for a product that is already published, its published status is preserved. When the product is not published, a successful category assignment moves it to proposed rather than directly to published.
This is a small conditional with an important business meaning. The intelligence workflow can improve live catalogue structure without accidentally unpublishing products, and it can prepare imported drafts without bypassing release.
The product's previous commercial state remains authoritative. AI changes the classification result it was asked to produce, not unrelated lifecycle decisions.
Require a real category link before proposing a draft
The platform also supports an explicit “propose categorised products” operation for a seller import.
It does not trust an import metadata label saying that categorisation succeeded. The database query selects seller-owned draft products and requires a current relationship to a real product category. Only those products move to proposed.
Draft products with no category link remain draft, and the response reports their count separately as uncategorised. An optional import identifier can limit the transition to one catalogue run rather than every draft owned by the seller.
This gives the operator a meaningful outcome: these products have a concrete catalogue placement and are now proposed; these others still need classification work.
The status transition follows the commerce relationship, not merely the model's narrative about what it intended to do.
Make “proposed” a real operating queue
Proposed is not a euphemism for published later in the same request.
It is a visible product state in seller and admin tooling. The platform can count proposed products for a supplier, list them separately and show the operator the size of the pending release.
This creates a pause between intelligence work and commercial exposure. The team can investigate unresolved products, understand how much of an import reached the proposal stage and decide when the seller's prepared set should move forward.
The evidence does not claim that every proposed product receives a documented line-by-line review. The release action operates at seller level. What the architecture proves is the deliberate boundary: the system does not equate successful AI classification with buyer visibility.
That boundary is valuable even when the human decision is “the prepared batch is good enough to publish now”.
Put the final action on the admin side
The supplier can import products and run categorisation, but the final bulk-publication surface belongs to administration.
The page identifies the seller, loads the number of proposed products and disables publication when there is nothing to release. An administrator may optionally choose a sales channel before clicking the explicit “Publish All” action.
This makes the scope visible at decision time. The operator knows which supplier and how many proposed products are affected. Sales-channel choice is not hidden in the AI job or inferred from a prompt.
The action also avoids a dangerous UI pattern: hundreds of independent publish requests from the browser. One administrative command stages the server-side work for the selected seller scope.
Human authority is expressed as a clear product operation, not as an informal instruction embedded in model text.
Treat publication as a background operation
A large release should not depend on one HTTP connection staying open.
When the administrator publishes, the backend first creates and stages a durable bulk-product job. The response is accepted with a job ID, transaction ID, pending status and a status URL. It reports the planned total without pretending that every product is already live.
The dashboard polls the job until it reaches completed, failed or cancelled. It can show processed count, failure message and terminal outcome. A click starts the work; the job record explains what happened afterward.
This is important for trust. If the browser closes, the operation still has an identity. If some part fails, the interface does not need to guess whether the catalogue is half published. Operators can refer to the job rather than repeating the action blindly.
Publication becomes observable operational work, not a loading spinner attached to a model result.
Avoid one event per product
Publishing a prepared supplier catalogue can affect many products at once.
A naive implementation updates each item through the browser and emits an independent search event for every row. That creates unnecessary request overhead and can turn a single release into a burst of overlapping Elasticsearch synchronisations.
The bulk path stages the seller's proposed products and processes them server-side. Catalogue synchronisation is coordinated around the bulk operation rather than asking the client to orchestrate individual product mutations.
This respects the business unit of work: the administrator is releasing one prepared seller set. The platform can track progress at product level while keeping one operation identity and one coherent downstream signal.
The architecture also gives retry and status tooling a durable place to live. A browser loop has neither.
Keep unresolved AI outcomes out of the release set
The categorisation pipeline preserves distinct exception reasons: no candidates, search failure, product-data conflict, no match and an invalid model category ID.
Those products do not acquire a valid category link and therefore cannot qualify for the propose transition that requires one. Successful products continue; unresolved products remain available for targeted review or reset.
This prevents the lowest-quality part of a batch from defining the fate of the whole import. The team can publish the prepared set while retaining a precise backlog for products that need better data, taxonomy work or another run.
It also prevents “uncategorised” from becoming a miscellaneous public bucket merely to increase completion percentage. No category is a review state, not a buyer-facing taxonomy decision.
Human control begins before the final button: operators retain visibility into what automation could not resolve.
Separate model confidence from release authority
A model may return a confidence score with its chosen category. That score can help prioritise review, but it is not a publication permission.
The transition to proposed depends on a valid, linked Medusa category. The transition to published depends on an administrative release operation. Neither boundary says “publish automatically above 0.9”.
This avoids false precision. Confidence describes the model's relationship to the candidates and evidence it received. It does not evaluate image quality, supplier fulfilment, commercial price or organisational assortment.
By keeping release outside inference, the marketplace can change its publication policy without retraining the classifier. It can add future quality checks, seller rules or channel requirements around proposed products while the categorisation contract stays stable.
The model remains specialised instead of becoming an accidental general manager of the catalogue.
Make rollback and unpublish use the same lifecycle language
Publication is not the end of product governance.
The admin system also treats unpublishing as a controlled bulk operation that moves products back to proposed and removes their buyer-facing channel relationship. That symmetry gives the status model ongoing value.
Proposed therefore means more than “newly imported and waiting”. It can also represent a previously live product deliberately withdrawn for correction while retaining its catalogue record and category work.
The team can reason about product state in business language: draft is still being prepared, proposed is ready for an explicit release decision, published is visible, and rejected records a negative decision.
Clear states reduce the temptation to encode release history in scattered metadata or naming conventions.
Why Medusa was the right foundation
Medusa provides product lifecycle states, category relationships and sales channels. The project extended those primitives with asynchronous AI categorisation, import review states and tracked seller-level bulk jobs.
This let us insert intelligence before publication without replacing commerce authority. Elasticsearch retrieves category candidates. The model selects among them. Medusa validates and links the category. The admin product lifecycle determines when the item becomes buyer-visible.
On a platform that treats publication as an unavoidable side effect of product creation, preserving this boundary would require fighting the core model. Here, the architecture could reflect the client's operating decision directly.
Choosing Medusa was valuable not only because it was extensible, but because the extension could rejoin a clear commerce lifecycle.
The AI-to-publication checklist
Before connecting catalogue AI to release, ask:
- What exact decision is the model authorised to make?
- Does ingestion preserve products already published?
- What state receives newly classified products?
- Is a real category relationship required before proposal?
- Are unresolved products counted separately?
- Can one import be scoped independently?
- Is the proposed set visible to operators?
- Who is authorised to trigger final publication?
- Is the affected seller and product count visible?
- Is sales-channel placement explicit?
- Does publication create a durable job?
- Can the UI distinguish accepted work from completed work?
- Are processed, failed and cancelled states observable?
- Is downstream search synchronisation coordinated as bulk work?
- Can published products return to proposed when withdrawn?
These questions preserve speed without giving inference hidden commercial authority.
The broader lesson
AI can prepare a catalogue without owning the moment it reaches buyers.
For this marketplace, we built the flow so valid categorisation moves non-live products into a proposed state. Products without a real category link stay out. An administrator sees the seller-level proposed count, chooses the release context and explicitly starts a tracked bulk-publication job.
That boundary is simple enough for the business to understand and strong enough for the architecture to enforce.
The model does the repetitive interpretive work. Medusa holds the lifecycle. The human operator decides when prepared catalogue data becomes a commercial promise.