- A supplier catalogue is rarely delivered once and left untouched.
- Descriptions change. Pack sizes evolve.
- For the marketplace operator, the request sounds simple: “Please import the latest file.” For the commerce platform, it is a dangerous instruction.
- That was the client problem we solved on a B2B procurement marketplace built with Medusa.
The client problem
A supplier catalogue is rarely delivered once and left untouched.
Descriptions change. Pack sizes evolve. New images arrive. Prices are corrected. A supplier adds products that the marketplace has never seen before. The next file may contain only the columns that changed, rather than a complete copy of every product.
For the marketplace operator, the request sounds simple: “Please import the latest file.” For the commerce platform, it is a dangerous instruction. Treat the file as a new catalogue and existing products may be duplicated. Treat blank cells as new values and useful data may disappear. Accept every unknown SKU and unreviewed products may become purchasable.
That was the client problem we solved on a B2B procurement marketplace built with Medusa. We designed a separate catalogue-delta path: existing seller SKUs can be updated through an explicit field policy, omitted values are preserved, and unknown SKUs are parked for an administrator rather than silently created.
The supplier can keep sending operational updates. The marketplace keeps control of its catalogue.
A catalogue update is not a catalogue replacement
The first architectural decision was to distinguish two business intentions.
A catalogue import says: these rows describe products that may need to be created and connected to a seller.
A catalogue delta says: these rows describe changes to products that already belong to this seller.
Those intentions cannot safely share the same default behaviour. In a creation flow, a new SKU is expected. In an update flow, a new SKU is an exception that needs a decision. In a complete catalogue, an empty field may be meaningful. In a narrow delta, the field may simply have been omitted because the supplier did not intend to manage it.
We therefore gave update files their own route through the import workflow. That route carries an explicit updates identity from ingestion through staging, validation and confirmation. The system does not have to infer the supplier's intention from the shape of a spreadsheet after processing has begun.
This small distinction protects the rest of the workflow. Every later step can ask one clear question: are we creating a catalogue, or applying a controlled change to an existing one?
Match the product through the supplier's SKU
An update needs a stable identity key.
Titles are not identities. Suppliers shorten them, translate them and improve them. Handles may have been generated by the marketplace or edited after publication. A manufacturer part number can be shared across packaging variations.
For this update path, the configured supplier SKU is the match key. During validation, the platform looks for an active variant with that SKU attached to a product owned by the same seller.
The seller boundary matters. In a multi-vendor marketplace, the same visible SKU pattern can occur in more than one supplier's data. A delta from one supplier must never update another supplier's product simply because a string matches.
We also deliberately avoid falling back to a coincidental handle match on the update route. If a new SKU happens to generate a handle already present in the catalogue, that collision is not permission to mutate the existing product. The row remains an exception for review.
The practical rule is simple: identity must be explicit, seller-scoped and consistent with the contract used to receive the file.
Let each supplier map the file it actually sends
Supplier files do not arrive with Medusa's preferred column names.
One supplier may call the key ITEM; another may use Stock Code. Price may mean pounds, dollars or cents. Product copy may be spread across description and specification columns. Some feeds include a thumbnail but no gallery. Others contain free-text fields with unexpected delimiters.
The platform stores a per-supplier update field map. It identifies the incoming SKU column and, when authorised, the columns for title, description, specifications, price, manufacturer, brand, unit of measure and thumbnail.
At staging time, the row is translated into the same canonical product vocabulary used by the downstream import system. Only mapped fields receive values. The original source row is also retained for the review surface, so an operator can understand what the supplier actually submitted.
For files with a known free-text column, the parser can reconstruct ragged rows around that column before mapping. This prevents an unquoted delimiter in a description from shifting the price and every following value into the wrong field.
Mapping turns a supplier-specific document into a controlled commerce instruction. It does not give the document unlimited authority.
Field ownership is the real safety boundary
Finding the correct product is only half the problem. The next question is: what is this feed allowed to change?
A supplier may own product copy and price but not publication status. It may provide a manufacturer name but not marketplace categories. A recurring commercial feed should not be able to overwrite relationships, approval state or internal merchandising data simply because those fields exist in Medusa.
The update workflow carries a field-policy snapshot. Validation uses that policy to decide whether a row contains a meaningful permitted change. Confirmation uses the same snapshot when applying the update.
This is important because a preview and an execution path must agree. If the review screen shows changes under one policy but confirmation applies a broader one, the control is cosmetic.
When the policy snapshot is missing from an update import, the confirmation route refuses to continue safely. That is the correct failure mode. The platform should not guess which catalogue fields a historical file was allowed to own.
Field policy converts “import this spreadsheet” into a narrow business contract: update these specific properties of these existing seller products.
An absent value must not erase an existing value
Delta files are often sparse.
Imagine a supplier sends SKU and price this week. The file contains no description column because descriptions did not change. If the importer converts every unmapped field to an empty update, a price refresh can wipe titles, descriptions, brands and images across the catalogue.
Our canonical transform uses preserve-on-empty semantics. An unmapped or blank price becomes an empty incoming value, never an invented zero. Optional fields that are not supplied remain absent from the effective change. The comparison and confirmation logic preserve the current catalogue value.
The same rule applies to textual fields. Empty placeholders are normalised before the update is calculated. Whitespace or formatting differences do not automatically become product mutations.
This distinction is easy to miss because both cases may appear as an empty cell in a CSV:
- “clear this field” is an explicit business instruction;
- “this feed does not own or supply this field” is no instruction at all.
A safe delta format needs a defined way to distinguish them. For this workflow, omission and blank mapped values preserve the current product rather than deleting information by accident.
Validate prices before they become commerce data
Price columns carry their own ambiguity.
A source may include currency symbols, formatting or integer values expressed in cents. The supplier configuration records how to interpret the field. The transform parses the value, converts cents when configured and reports invalid price text as a row error.
An explicit zero price is not treated as an ordinary update. It is skipped under the import price policy rather than turning an existing product into a free item.
Rows whose permitted values would not change the current product are also skipped. That no-op detection uses the same normalised comparison logic as the review diff and confirmation path. A supplier can resend a file without creating thousands of phantom updates caused by whitespace or formatting alone.
The business benefit is clarity. Operators can distinguish changed, unchanged, invalid and exceptional rows. The system does not pretend that every line in a new file represents work.
Park unknown SKUs instead of creating them
The most important difference between a catalogue and a delta appears when the SKU does not exist.
Automatically creating the product would be convenient, but it would change the meaning of the feed. A routine update could introduce new assortment, incomplete merchandising, missing category assignments or products that have not passed the marketplace's publication process.
The update route never enters the normal product-creation machinery. After existing and deleted products have been classified, remaining new SKUs are moved into a durable pending-new-product table. Their source row, seller, import, row number and inbound email context are preserved.
The original import row is marked as parked with an explicit review reason. A unique import-and-row constraint prevents the same row from being parked twice if processing is retried.
This creates a clean operational boundary:
- existing active SKU: evaluate a permitted update;
- unchanged SKU: skip it;
- deleted product: do not silently resurrect it through the delta;
- unknown SKU: park it for a catalogue decision.
The marketplace can accept frequent supplier maintenance without delegating assortment approval to an attachment.
Give administrators a real review queue
Parking is useful only if somebody can act on it.
The platform exposes administrative routes that list pending new products, group them by import and seller, paginate wide source rows and export the parked data as CSV. The Control Center can also surface pending-new-product work and route the operator to the relevant review screen.
An administrator therefore sees which supplier introduced the new SKUs, when the import arrived and which raw values accompanied each row. They can assess whether the products should enter a proper catalogue-onboarding workflow rather than attempting to reverse-engineer the event from logs.
This is a recurring pattern in marketplace architecture: automation should separate the obvious majority from the commercially meaningful exceptions. Existing products can move through the controlled update path. New assortment becomes visible work.
The review queue is not an admission that the import failed. It is the product mechanism that keeps two different business decisions—maintenance and onboarding—from being conflated.
Keep the whole import traceable
A supplier needs more than a final “success” message.
Rows are staged durably with their source values, row index, derived SKU, status and error. Duplicate handles and SKUs inside the same file are detected deterministically. Existing products become pending updates. Invalid and zero-price rows are skipped or failed with reasons. Unknown SKUs become parked work.
The import can report counts across those states. Review and confirmation operate against the same import identity. Product search synchronisation is queued after confirmed changes rather than being hidden inside each row mutation.
This gives operations a comprehensible answer when a supplier asks what happened:
- how many rows were received;
- which rows matched existing products;
- which values produced actual changes;
- which rows were invalid or duplicates;
- which SKUs need a new-product decision.
Traceability is what makes recurring automation supportable. Without it, every discrepancy becomes an engineering investigation into a file that has already been replaced by next week's version.
Why Medusa was the right foundation
Medusa already supplied the product, variant, pricing and workflow foundations. The client problem was not to replace those foundations with a spreadsheet engine. It was to extend them with supplier-specific ingestion and marketplace governance.
We added durable import records, streaming staging, seller-scoped identity, policy-bound comparison, review states and administrative exception handling around Medusa's commerce model.
That is the architectural value of choosing an extensible commerce engine. The standard product model remains useful, while the platform can express a client-specific rule that a generic importer rarely understands: a supplier may maintain approved fields on its existing products, but it may not silently create assortment through the same feed.
A closed platform might force this distinction into fragile middleware or manual spreadsheets. Here it became a first-class workflow connected to the catalogue and operator experience.
A practical catalogue-delta checklist
Before automating a supplier update feed, answer these questions:
- Is the file a complete catalogue or a delta against existing products?
- Which seller-scoped value is the stable product identity?
- Which incoming column maps to each canonical commerce field?
- Which fields is this feed authorised to change?
- Is that policy preserved from preview through confirmation?
- Does a blank value mean clear, preserve or invalid?
- How are currencies, cents and malformed prices interpreted?
- Are unchanged rows detected through the same comparison used by review?
- Can duplicate rows be explained deterministically?
- What happens when a SKU belongs to a deleted product?
- Are unknown SKUs created, rejected or parked for review?
- Can an operator inspect and export the original exceptional rows?
- Does retry preserve one identity for each parked row?
- Is search synchronisation triggered after confirmed catalogue changes?
If those decisions are implicit, the spreadsheet controls the marketplace. If they are explicit, the marketplace can safely consume the spreadsheet.
The broader lesson
The client did not need another bulk product creator.
They needed suppliers to maintain a large, living catalogue without being able to rebuild it accidentally.
We separated update intent from catalogue creation, matched products within seller scope, translated supplier columns through a stored map and limited changes through an explicit field policy. Blank inputs preserve existing values. No-op and invalid rows receive meaningful states. Unknown SKUs enter an administrative queue instead of becoming products.
The result is a catalogue workflow designed around business authority, not just file parsing.
That is how WeAreSouk extends Medusa for complex marketplace operations: keep routine supplier work fast, make exceptions visible and ensure every automated change stays inside a contract the business can explain.