- A supplier catalogue contains product titles, SKUs, prices—and ten image URLs per row.
- Those URLs work today. They may be slow tomorrow, return a login page next month or disappear when the supplier reorganises its CDN.
- Copying the URLs directly into Medusa would make the marketplace borrow a critical part of its product experience from systems it does not operate.
- For a supplier-driven catalogue, we built an asynchronous image-localisation lifecycle.
The client problem
A supplier catalogue contains product titles, SKUs, prices—and ten image URLs per row.
Those URLs work today. They may be slow tomorrow, return a login page next month or disappear when the supplier reorganises its CDN. They may also deliver files that are far larger than the storefront needs.
Copying the URLs directly into Medusa would make the marketplace borrow a critical part of its product experience from systems it does not operate.
For a supplier-driven catalogue, we built an asynchronous image-localisation lifecycle. The import records what media should exist. A separate worker acquires and validates each source, creates deterministic display and thumbnail renditions, stores them through the platform's file service and promotes only a complete, current bundle into the Medusa product. Search is refreshed afterwards, and incomplete work remains visible to operators.
The business capability is simple: supplier media becomes marketplace media.
The client problem: a remote URL is not a product asset
A URL proves only that a resource can be requested at one moment.
It does not guarantee availability, response time, content type, dimensions, byte size or long-term ownership. The same URL can later return different bytes. Different URLs can return the same image. A product may be updated while an older background download is still running.
Storefronts need a stronger contract. A product image should have predictable dimensions and weight. The primary thumbnail should be stable. Media order and variant relationships should survive replacement. Operators should know whether an imported product has all the images it expected.
The catalogue import therefore does not treat the supplier's URL as finished public media. It treats it as a source instruction that must pass through a controlled lifecycle.
That separation lets product creation finish without making remote downloads part of the import transaction.
Capture media intent during the import
The import normalises the non-empty image sources, removes duplicates and limits the number accepted for one product. It also preserves their source slots so image order can be reconstructed.
After terminal product processing, the platform records an image-localisation expectation tied to the import and seller. Its expected count is derived from durable staged rows whose products were actually created or reconciled.
If no image descriptors exist, the expectation reaches a terminal no_images state. If media is expected, it becomes pending and eligible for asynchronous materialisation.
This is more reliable than launching a background promise from inside a row callback. The expectation is a business record: for this completed import, these products should eventually have this many localised image slots.
The staged catalogue remains the recovery anchor. Large source payloads do not need to travel through every workflow invocation.
Keep remote sources out of public product data
Supplier URLs can reveal infrastructure, signed query parameters or credentials. They also become stale once the marketplace owns a local rendition.
The localisation lifecycle therefore separates source provenance from public product projection. Before worker execution, source URLs are protected in an encrypted envelope tied to the seller and intent. The workflow receives a compact run identity rather than a list of raw URLs.
The final Medusa image contains the local display URL and controlled provenance metadata, not the supplier address as the public asset.
This boundary has an architectural benefit beyond confidentiality. Internal source lineage can evolve independently from storefront contracts. A supplier can move hosts while the marketplace keeps serving the same owned media until a new source is deliberately processed.
The product points to what the marketplace can operate; the private registry remembers where it came from.
Run localisation outside the catalogue transaction
Image acquisition and decoding are variable workloads.
A remote server may respond slowly. A large image may require substantial memory to decode. Uploads can succeed one rendition at a time. Search indexing may be temporarily unavailable.
Putting that work inside product creation would hold the catalogue pipeline hostage to external media. Instead, a dispatcher selects bounded pending work, creates a run with a stable transaction identity and launches a Medusa workflow whose input contains only the run ID.
The worker claims intents through leases. It can process them independently and record retryable or permanent failures without rolling back the product that was already created.
This lets the marketplace accept a catalogue row and make media completion observable as its own lifecycle. The product does not become dependent on one long synchronous request chain.
Acquire bytes, not appearances
The worker fetches the remote source into a private temporary boundary and validates the content before transformation.
The detailed network and file-security controls deserve their own article. For this capability, the important point is that a successful HTTP response is not sufficient. The system needs validated image bytes, a detected media type, dimensions and a cryptographic digest.
It also stores source validators such as ETag and Last-Modified when available. A later request can use those validators, but a 304 Not Modified is useful only when a complete local bundle already exists for the current transformation policy. Otherwise, the worker requests the bytes unconditionally and validates them again.
This prevents an upstream caching response from being mistaken for a finished marketplace asset.
The digest identifies the content the platform actually received, not merely the URL used to request it.
Reuse identical content safely
Supplier catalogues often repeat the same image across products, variants or changed URLs.
After acquisition, the worker looks for a complete local asset with the same source digest and transformation policy. If one exists, the intent can reuse it instead of decoding and uploading the bytes again.
When multiple workers encounter the same new content concurrently, an asset reservation decides which worker owns creation. A non-owner waits for the winning complete bundle rather than publishing a second copy.
Deduplication is therefore based on content and policy, not URL equality. Two different supplier addresses can produce one owned asset when their bytes are identical. The same URL can produce a new asset when its bytes change.
That is the correct identity rule for media processing: the source location explains provenance; the digest and policy define the rendition bundle.
Produce two deterministic storefront renditions
The source image is not served directly.
The current policy creates a WebP display rendition and a WebP thumbnail. The display image fits within 1,200 pixels wide and a one-megabyte budget. The thumbnail fits within 480 pixels and a 120-kilobyte budget. Images are rotated according to metadata and never enlarged beyond their source dimensions.
Encoding begins at a configured quality and steps down until the byte budget is met, without going below a policy floor. If a rendition cannot satisfy its budget, the bundle fails rather than silently publishing an oversized file.
The two transforms run sequentially inside an isolated decoder process with bounded memory and wall time. A decoder crash or hang does not take down the Medusa workflow worker.
These constraints give the storefront a predictable media contract while retaining an explicit version for future policy changes.
Checkpoint partial work without publishing it
Display upload may succeed before thumbnail upload. A retry should not automatically repeat completed work, but the product should not point to half a bundle.
Each uploaded rendition receives a durable checkpoint containing its file ID, URL, media type, dimensions, byte size and policy version. On retry, the worker reads those checkpoints and creates only what is missing.
The asset becomes complete only when both display and thumbnail checkpoints are valid under the current policy. Promotion refuses an incomplete bundle.
This separates operational progress from public truth. A stored file can exist without yet being the product's image. Checkpoints make recovery efficient; the promotion gate keeps the storefront coherent.
The same pattern is useful across commerce systems: resumable work may be partial internally, while the customer-facing transition remains atomic at the domain boundary.
Prevent an old import from winning a race
Product media can change while background work is running.
Every localisation intent carries a generation, source lineage and protected source identity. Before promotion, the worker verifies that the intent is still current, its desired asset is the one being promoted and the complete bundle uses the expected policy.
Promotion runs under a product lock. It writes the managed image, then reloads the fence and verifies a unique promotion marker. If a newer import or concurrent media edit has replaced the intent, the transaction fails instead of making the stale image live.
This is crucial for merchant confidence. Asynchronous processing must not let completion order decide which image becomes authoritative. The newest authorised product intent must win.
Generations turn time into an explicit business rule.
Preserve product image semantics during promotion
Replacing an image URL is not enough.
The promotion logic preserves the intended slot, existing image rank and variant associations. It updates the product thumbnail only when the promoted image corresponds to the currently selected image—or when the first slot fills an empty product.
The Medusa image metadata records the managed asset, intent, generation, source digest, policy version, display and thumbnail properties and promotion marker.
That provenance lets operators and reconciliation jobs distinguish platform-managed images from unrelated manual media. It also explains which local bundle currently backs the product image.
If the product was deleted before promotion, the asset becomes an orphan candidate and the intent is cancelled rather than recreating a relationship to a missing product.
Media localisation respects the product lifecycle instead of treating storage as the final authority.
Refresh search only after Medusa is canonical
Product cards and search results may use image URLs projected into Elasticsearch.
After successful Medusa promotion, the intent moves into a search-pending state and the product projection is synchronised. Only then can the localisation lifecycle become terminal.
If search synchronisation fails, the local asset and Medusa mutation do not need to be discarded. The intent records that the remaining work is search projection and can resume from that boundary.
This ordering keeps ownership clear: Medusa is the canonical product record; Elasticsearch reflects it. Search never becomes the place where an image exists first.
The marketplace can therefore distinguish “media transformed”, “media promoted” and “media visible in discovery” instead of collapsing them into one ambiguous success flag.
Give operators a reconciliation surface
Background media cannot be trusted merely because a job was launched.
The project tracks expectations, materialised intents, runs, rendition checkpoints, promoted assets and search state. Reconciliation can recover stale leases, resume promotions, identify orphaned assets, terminalise no-image expectations and recompute counts.
The control centre turns those conditions into actionable incidents: localisation never launched, a run stalled, only part of the image set completed, a failure became permanent, a rendition is missing, counts disagree or search is overdue.
Authorised operators can retry eligible failures or run reconciliation with an audited reason.
This is what makes the feature operable. A merchant does not need a promise that external image processing can never fail. They need the system to reveal which product is incomplete and which recovery action is appropriate.
A practical image-localisation checklist
Before importing supplier media into Medusa, ask:
- Are duplicate and empty source URLs removed?
- Is the number of images per product bounded?
- Are original slots preserved?
- Is expected media recorded after catalogue processing?
- Do source URLs stay outside public product projections?
- Is localisation asynchronous and durably dispatchable?
- Are remote bytes validated before decoding?
- Is content identity based on a digest rather than the URL?
- Can complete renditions be reused under the same policy?
- Are display and thumbnail dimensions and byte budgets explicit?
- Is decoder failure isolated from the workflow worker?
- Can partial uploads resume without partial publication?
- Must both renditions exist before promotion?
- Does a generation fence prevent stale work from winning?
- Are rank, variant links and thumbnail selection preserved?
- Does Medusa become canonical before search sync?
- Can operators find stalled, partial and inconsistent work?
If the only stored fact is the supplier URL, most of these guarantees are impossible to prove.
The broader lesson
Medusa provides an extensible product media model. The client's supplier ecosystem provided remote image references with no storefront guarantee.
We connected those worlds through a durable localisation lifecycle: import expectations, private source lineage, validated acquisition, content-based reuse, policy-versioned renditions, resumable checkpoints, generation-fenced promotion and explicit search synchronisation.
The marketplace gains consistent images it owns and can operate. Supplier catalogues remain valuable sources without becoming runtime dependencies.
That is the architectural advantage of an extensible commerce engine: when the business needs more than “store this URL”, the media lifecycle can become a real product capability.