The CSV uploaded perfectly. The products still could not be sold.

The client problem

A supplier sends a catalogue containing titles, SKUs, descriptions, prices, specifications, image URLs and stock.

The file parses. Every row appears in the database. The import is declared successful.

Then the problems begin. A product has no seller relationship. A variant has no price set. Inventory exists without a stock location. The item is missing from the sales channel. Checkout cannot find a compatible shipping profile. Remote images disappear or load slowly. Search receives a record before a human has reviewed it.

The client did not need a CSV uploader. It needed a reliable translation from each supplier's catalogue language into a complete Medusa commerce model.

For a multi-vendor marketplace, we built that translation as a staged workflow. Suppliers map their columns once. Rows are preserved and classified durably. New products are created with the relationships required by pricing, inventory, fulfilment and discovery. They remain drafts until the catalogue is ready for publication.

An import is complete only when the resulting product can survive the rest of the buying journey.

The client problem: every supplier describes the same product differently

One supplier calls the identifier ITEM. Another uses SKU, Part Number or an internal code. Price may arrive as a decimal, formatted currency or a field whose meaning depends on the feed. Specifications can occupy one JSON-like cell or dozens of columns. Image fields may be repeated, concatenated or completely absent.

Hard-coding one file layout creates a demo, not an import capability.

The marketplace needed to onboard several suppliers and accept recurring feeds without asking engineering to rewrite the parser every time. At the same time, source flexibility could not weaken the target contract. Medusa still needs a stable product title, handle, variant identity, price, inventory relationship and commercial ownership.

The solution separates two questions:

1. how does this supplier express its data?
2. what does a valid marketplace product require?

A reusable mapping answers the first. The import workflow enforces the second.

Save the supplier mapping as an operational asset

The Vendor application lets the operator connect source headers to canonical fields.

Single-column mappings cover values such as title, SKU and price. Multi-column mappings collect details and specifications. Excluded headers make an intentional decision about data that should not enter the catalogue. Value rules explain formats and delimiters.

That configuration becomes a seller-owned import preset. When the supplier sends the next file with the same structure, the platform can apply the same translation rather than repeating the setup manually.

Presets matter beyond convenience. They turn onboarding knowledge into a durable contract. The system can say which column produced the marketplace SKU, which fields were ignored and how a specification was interpreted.

The canonical row is stored with its original source values where the route requires review. An operator can therefore trace a product decision back to the incoming file instead of inspecting only the transformed result.

Stage rows before creating commerce records

The workflow does not create a Medusa product as soon as the parser emits a row.

It first streams canonical rows into a dedicated staging table. Each row receives an import identity, source row number, raw data, derived handle, seller-scoped SKU, status and error field.

Staging provides three benefits.

First, the source survives beyond the upload request. If later processing stops, the platform knows which rows remain pending.

Second, validation can compare the entire file and the current catalogue before mutation. Duplicate SKUs, existing products and ownership conflicts are easier to classify in sets than one row at a time.

Third, processing can read bounded batches from the database. The workflow carries references and progress, not a growing array of catalogue objects in orchestration state.

The staging buffer writes rows in groups, and the product step reads pending rows in deterministic order. File size changes the amount of work, not the shape of the workflow.

Decide product identity in the supplier's context

Marketplace identity cannot rely on a raw supplier SKU alone.

Two suppliers may both sell a product labelled 1001. That does not make their catalogue records the same commercial item. The import derives a seller-scoped variant identity and a stable handle from the canonical row.

Before creation, bulk validation detects duplicate handles and SKUs inside the file. The earliest row remains the candidate; later duplicates receive an explicit skipped status. It also checks the existing catalogue in the context of the current seller.

An identity already owned by another seller is not silently adopted. An active product belonging to this seller is classified for update. A soft-deleted product can be classified for controlled restoration. A genuinely new identity stays on the creation path.

This prevents the uploader from turning an ambiguous key into cross-supplier ownership.

Build the whole Medusa product graph

A new row becomes more than a product record.

Inside one bounded database transaction, the creation path prepares the connected records required by the marketplace:

• the draft product and its import metadata;
• a variant with the seller-scoped SKU;
• its option and option value;
• a price set and USD price;
• an inventory item and inventory level;
• the seller-to-product relationship;
• the seller-to-inventory relationship;
• sales-channel availability;
• the product shipping-profile relationship when the seller has a configured default;
• structured attributes derived from supplier details and specifications.

Creating these relationships together avoids a misleading partial success. If a batch fails before its transaction completes, it does not leave half of that graph looking sellable.

Medusa remains the commerce engine. The import supplies the domain translation needed to use its pricing, inventory and fulfilment capabilities correctly.

Require the supplier context that later commerce depends on

The import resolves the seller's stock location before creating products.

That is a business prerequisite, not an incidental foreign key. Stock needs a place, and later fulfilment needs to know where a variant can be supplied.

The path also looks for the seller's default shipping profile. The standard Medusa product workflow would normally create that relationship through its own hooks. Because this high-volume path writes the graph in controlled batches, it deliberately reproduces the required relationship.

If no stock location exists, the import cannot build a valid inventory context and stops. If the default shipping profile is unavailable, the record can be created only with a visible fulfilment gap that must be resolved before the product is considered operationally ready.

The important principle is to preflight downstream dependencies. An uploader should not celebrate a row that checkout will reject later.

Keep new products in draft state

The creation path writes products as drafts.

That protects the marketplace from source data that is structurally valid but not ready for buyers. A title may need correction. A product may not yet have an approved category. Images may still be localising. Specifications may need review. Search should not expose the item before those gates are complete.

Draft state separates technical ingestion from commercial publication.

This is especially important when a supplier sends recurring files. Automation can do the repetitive translation and validation without granting the source file unilateral authority over the live catalogue.

Once review and categorisation are complete, publication can use the platform's normal catalogue controls and trigger the appropriate search projection.

The supplier gains speed without bypassing marketplace governance.

Treat remote images as work to complete, not finished assets

Supplier image URLs are useful inputs, but they are not a dependable storefront media strategy.

The import captures image descriptors and the expected slots for each product. A separate localisation pipeline can then fetch, validate, store and render those images under marketplace control.

This separation keeps network operations out of the core product transaction. A slow or unavailable supplier server does not need to hold the entire catalogue batch open. It also lets the media pipeline apply security, content-type and deterministic rendition rules that belong to image handling rather than product identity.

Until the managed media is ready, the product remains under review. The import does not confuse “the supplier gave us a URL” with “the marketplace owns a reliable image”.

Preserve attributes without reducing them to metadata soup

Supplier details and specifications often contain the values buyers actually use to compare products.

The pipeline uses an attribute mapper to connect incoming keys and values with the marketplace's structured attribute model. Brand and manufacturer relationships are handled as named identities rather than repeated free text. Unit of measure and specifications can become filterable, comparable catalogue facts.

The raw row remains available for traceability, but the live product does not rely on every consumer reinterpreting arbitrary JSON.

That distinction affects discovery later. Search can project canonical attributes. Product comparison can use stable dimensions. Order history can snapshot the purchased meaning. A future update can compare incoming structured values with the current catalogue rather than treating formatting differences as business changes.

The import is the first point at which supplier vocabulary becomes marketplace vocabulary.

Keep catalogue and inventory updates separate

The full creation path establishes an initial inventory item and level because a new variant needs an inventory model.

Recurring catalogue updates follow a different contract. They can change approved catalogue fields, but they do not overwrite on-hand quantity. Stock belongs to its own feed and operational lifecycle.

This boundary prevents a descriptive catalogue file from resetting inventory with a stale or absent value. It also lets high-frequency inventory feeds run independently of slower product-content changes.

The business sees one product, but the platform recognises different sources of authority: catalogue content, price, stock, media and publication can each have an explicit update path.

That is safer than accepting every non-empty column as permission to overwrite the current record.

Make every outcome visible to the operator

The import record stores its filename, seller, route, status, row counts, processing errors and timestamps. Staged rows retain their own status and error.

The operator can distinguish rows that were created, identified as updates, identified for restoration, skipped as duplicates, rejected by price policy, blocked by another seller's ownership or failed during processing.

Progress is written as the workflow stages and processes rows. If execution stops, the durable row state shows what remains rather than forcing the supplier to upload blindly again.

This is what turns a batch job into an operable product feature. A supplier does not need to understand workflow internals. They need a trustworthy answer to “what happened to my catalogue?”

A practical supplier-import checklist

Before calling a catalogue import complete, ask:

1. Can each supplier save and reuse its column mapping?
2. Are excluded fields explicit?
3. Is the canonical row preserved for review?
4. Are rows staged before catalogue mutation?
5. Are duplicate handles and SKUs classified in bulk?
6. Is identity scoped to the seller?
7. Does a new product receive a variant, option and price set?
8. Is inventory linked to a real seller stock location?
9. Is the seller relationship created?
10. Is the product attached to the correct sales channel?
11. Is a shipping profile available for later fulfilment?
12. Are attributes promoted into structured catalogue data?
13. Are remote images delegated to a controlled media pipeline?
14. Do new products remain drafts until review finishes?
15. Can an operator see row-level outcomes and resume safely?
16. Are catalogue updates prevented from overwriting inventory?

A green parser answers none of these questions by itself.

The broader lesson

Medusa gives us solid primitives for products, variants, prices, inventory, sales channels and fulfilment. A supplier file gives us none of their relationships automatically.

We chose Medusa because those primitives are extensible. The import can translate each supplier's source model into the complete commerce graph without inventing a parallel catalogue engine.

For this marketplace, reusable presets capture supplier vocabulary, durable staging creates a safe decision point, bounded transactions create complete draft products, and separate media and review paths finish the work before publication.

The file upload is the beginning. The product is ready only when the marketplace can price it, stock it, fulfil it, find it and explain how it got there.