Product Imagery in a Commerce Platform Integration

What a commerce integration does with product imagery

Product imagery in a commerce platform integration is the set of images and video attached to catalogue entries — products, variants and SKUs — through a connector that stores the association in the commerce platform’s own model and serves the media from a media platform rather than from the storefront’s file system. Cloudinary’s commerce integrations overview lists the platforms it ships connectors for; the commercetools integration is the one documented in most detail and is used here as the worked case. The points below hold for any of them.

The association lives in the platform’s model, not in a filename

The first thing an integration does that a folder of images cannot is record which asset belongs to which product in the commerce platform’s own data. In the commercetools connector that association is written against the product or variant record itself, so it is part of the catalogue rather than a convention layered on top of it. In the other direction, the asset in the media library carries the product’s identifier — a SKU or product key — as metadata or a tag, so the link is readable from either side.

The practical consequence shows up at re-import time. A catalogue re-import — from a PIM, an ERP or a spreadsheet — rewrites product records wholesale. A filename convention such as SKU-1234-front.jpg survives that only if every system in the chain preserves the naming rule and nobody renames an asset in the meantime; the moment a designer exports SKU-1234-front-v2.jpg, the link is broken and nothing reports it. An association held in the platform model is re-established by the connector on the next sync because it keys on the product identifier, which the re-import preserves. This is the same problem keeping product media in step with a PIM covers from the PIM side: the identifier, not the file, is the durable handle.

It also determines what the integration is allowed to see. Connectors typically operate on a scoped part of the media library rather than the whole account, and the folder mode chosen at setup decides how product identifiers map onto folder paths — see folder modes and what a no-code integration is allowed to see for what each mode exposes.

Renditions are named transformations, not files

A product page uses a small, defined set of renditions of each image: a thumbnail in listings and the cart, a gallery size on the product page, and a zoom rendition that is only fetched on interaction. Storing each of these as a separate uploaded file triples the asset count and, worse, freezes the design: when the gallery column changes width, every gallery file has to be regenerated and re-uploaded.

Defining each rendition as a named transformation in the media platform inverts that. The storefront asks for t_gallery or t_zoom and the platform derives the pixels on request from the single master, caching the result on the CDN. Changing the gallery from 800 px to 960 px is one edit to the named transformation; every product picks it up on the next request and nothing is re-uploaded. Cloudinary’s general guidance on integrating with other platforms frames this as the reason to reference the master and transform at delivery rather than to store derivatives: the master is the source of truth and the renditions are a view of it.

The discipline this requires is that the storefront theme references the names and never hard-codes transformation parameters inline. Inline parameters in a template work until two templates disagree about what a thumbnail is, and then the listing page and the cart show the same product at two crops. Named transformations are also where format and quality decisions belong — the storefront should not have to know whether a given browser gets AVIF or WebP.

Zoom and gallery views are where the bandwidth goes

On a product page the thumbnail strip is small and the hero gallery image and zoom rendition are large; a zoom rendition can be several times the byte size of the gallery image, and a shopper who zooms fetches it for every image they inspect. Across a store, those two renditions account for most delivered media bytes, and bandwidth is one of the three things Cloudinary meters — one credit buys 1 GB of delivered bandwidth, 1 GB of managed storage, or 1,000 transformations, per its credits FAQ as checked on 2026-08-18.

So the optimisation decisions that matter are made in exactly two named transformations. Whether the zoom rendition is served at the display’s device-pixel ratio or capped at a fixed maximum, whether it uses automatic quality, whether it is lazy-loaded behind an interaction rather than preloaded, and whether the gallery serves a responsive set of widths rather than one oversized file — those choices decide most of the store’s media cost. Getting the thumbnail transformation perfect changes almost nothing.

Because transformations and bandwidth are metered over a rolling 30-day window rather than a calendar month (same FAQ, same date), a launch-week spike in zoom traffic ages out on its own; storage does not, which matters for the next two points. What a hosted automation itself costs to run, as distinct from the media it moves, is treated separately in what a hosted media automation actually costs.

Variant imagery is where the asset count comes from

A catalogue of 2,000 products does not have 2,000 images. Each product has several angles — front, back, detail, on-model — and each colourway usually needs its own set, because a recolour of the front shot rarely passes for the real product. If those were stored as separate rendition files the multiplication would be colourways × angles × renditions; with named transformations it is colourways × angles, and the renditions are derived. Either way, variant imagery is the term that dominates the count, and it is the term merchandising teams underestimate because they think in products.

The integration’s job here is to attach imagery at the variant level where the platform models variants, so that selecting a colourway on the storefront swaps to that variant’s images rather than showing a generic product set. The commercetools connector works against variants for this reason. An integration that only associates media at the product level pushes the variant logic into the theme, where it is reimplemented per storefront and breaks on the first product with a non-standard variant axis.

Two things follow for the media library. Storage is a current total — one credit per GB held — so a variant explosion shows up directly and does not age out. And alt text has to be written per variant, not per product, if it is to describe the colourway on screen; that is a job for an automation rather than a spreadsheet, and alt-text generation inside a media automation flow covers the flow.

What happens when a product is deleted

The evaluation question that separates integrations is not how they upload but what they do on delete. When a product or variant is removed from the catalogue, its images are still in the media library, still counted against storage, still cached at the CDN if anything links to them, and no longer reachable from any catalogue record that would tell an operator they are orphaned. Nothing fails, nothing alerts, and the storage total simply never goes down.

An integration worth using does one of three things on delete, and its documentation should say which: it deletes the associated assets; it tags or moves them into an orphan state that a scheduled cleanup can act on; or it leaves them and provides a report of assets whose product identifier no longer resolves. Because the association is held in the platform model, the connector is the only component that reliably knows an asset has become orphaned — a filename convention cannot tell you, and neither can the storefront. If the connector offers none of these, the cleanup has to be built as a separate flow that reconciles the library’s product-identifier metadata against the catalogue, which is a reasonable first media automation but one that should not be needed.

The cost is deferred, which is why it is unnoticed. A store that has been live for three years and refreshed its catalogue each season may be paying for four seasons of imagery, of which one is on sale. Deleting assets reduces the storage total immediately, so the remedy is cheap once the orphans are identifiable; the expensive part is that nothing identified them.

What to check next

• The connector’s own page for the platform in question — the commerce integrations overview is the index — for whether it associates at product or variant level and what it does on delete.
• The folder mode the connector is configured in, since it decides which part of the library the connector can associate from.
• The named transformations behind the gallery and zoom renditions, because that is where the delivered bytes are decided.
• The storage line on the last invoice against the count of live products, as a first estimate of how much orphaned media is already accruing.