The Magento media gallery is the Admin tool for uploading, organizing, and reusing images on your server. For a jewelry store, it is only half of the image story. Your product photos live in each product’s Images and Videos section, and supplier feeds can add or replace them at scale. This guide shows you how to turn on the enhanced gallery, what it does and does not control, and how to keep a jewelry catalog tidy when thousands of supplier images flow in.
TL;DR
- Enable the enhanced gallery under Stores > Settings > Configuration > Advanced > System > Media Gallery, then open it at Content > Media > Media Gallery.
- The CMS gallery manages reusable content assets. Product image order, roles, labels, and visibility are set on each product, and a feed must respect that difference.
- Media processing runs through queue consumers, so a blank gallery right after an import is often a timing issue, not missing inventory.
- Match existing images by a stable identifier or controlled filename. Re-sending URLs without that can create duplicates and bloat your media folder.
- Test variant imagery (metal, stone, style) on configurable jewelry products before you launch a collection.
Table of Contents
- What the Magento media gallery actually is
- How to enable the enhanced gallery
- Managing assets: what you can do in the gallery
- Gallery assets vs. product images: the distinction that matters
- Choosing and ordering jewelry images
- Variant imagery for configurable jewelry
- Why a blank gallery after import is often just queues
- Preventing duplicate images when feeds sync
- Video in the gallery and on the page
- Our perspective: treat the catalog as a living thing
- A practical workflow for supplier imagery
- Where JewelCloud fits
- FAQ
- Sources
What the Magento media gallery actually is
With Adobe Commerce or Magento Open Source 2.4, merchants can use an enhanced Media Gallery to organize and manage media files on the server. It keeps the functions of the older media storage and adds an improved interface and closer Adobe Stock integration.
You reach it in several places: from Content > Media > Media Gallery, while editing pages and categories, and inside the Content Editor. Page Builder can also pick an existing gallery asset.
For a jewelry retailer, think of it as your library for editorial and campaign imagery: homepage banners, category headers, lookbook photos, and size guides. It is not where your ring and pendant photography is merchandised. That distinction causes most of the confusion we see, so it gets its own section below.
How to enable the enhanced gallery
The steps are short, but the deployment around them deserves attention.
- In the Admin, go to Stores > Settings > Configuration > Advanced > System.
- Open the Media Gallery section.
- Set Enable Old Media Gallery to No.
- Save the configuration.
- Refresh any invalid cache types.
- Open Content > Media > Media Gallery.
Those steps follow Adobe’s documented enablement workflow.
One caution for larger catalogs: the switch is not purely a setting. Initial indexing depends on background consumers, which we cover below. Plan for queue-worker monitoring and a cache refresh as part of the release, not as an afterthought. If you have been searching for answers because folders or new uploads are not showing up, the queue is the first place to look.
Managing assets: what you can do in the gallery
According to Adobe’s asset-management documentation, administrators can upload, search, filter, edit, use, and delete assets. You can edit the Title, Description, and Tags or keywords of an asset. You can also filter by where an asset is used (categories, products, pages, or blocks), plus store view, license status, content status, upload date, and modification date.
The same documentation notes support for XMP and IPTC metadata, which is useful if your photographers already embed rights and caption data in the files.
Practical uses for a jewelry store:
- Find unused assets before a seasonal cleanup, by filtering on usage.
- Track license status on stock imagery so a bridal banner does not go live without clearance.
- Standardize titles and keywords for campaign images so your merchandising team can search them.
Adobe also notes that the enhanced gallery can manage media acquired through its Stock integration, including licensing saved previews. Keep that stock imagery separate from supplier product photography. Their licenses and owners differ, and you should confirm license status before reusing a stock image in a storefront banner.
Gallery assets vs. product images: the distinction that matters
This is where jewelry catalogs go wrong. Two systems handle images:
| CMS Media Gallery | Product Images and Videos | |
|---|---|---|
| Purpose | Reusable content assets | Merchandising of one product |
| Where used | Pages, blocks, categories, Page Builder | Product page, listings, swatches |
| Controls | Title, description, tags, license, usage | Order, roles, labels, visibility |
| Typical jewelry content | Banners, lookbooks, guides | Ring, pendant, and earring photography |
Per Adobe’s product-media guidance, each product can hold multiple images and videos, and you can rearrange their order and control how each is used. For large catalogs, Adobe recommends batch importing images rather than uploading them one at a time.
At a specific store-view scope, you can override image order, alt text, the Base, Small, Thumbnail, and Swatch roles, and whether an image is hidden from the product page. Images uploaded at the default scope are visible across store views unless you override them.
The practical rule: write down which assets belong to product media, which belong to editorial content, and how a supplier filename maps to a SKU and variant. That one-page policy saves hours later.
Choosing and ordering jewelry images
Image order, roles, alt text, and visibility are merchandising decisions, not file-storage details. The first image is the one shoppers see in listings, so choose it for the buying context. A clean front or three-quarter view of an engagement ring usually works. A pendant may need a worn shot to convey scale.
Then let supporting images answer the questions a shopper would ask a counter associate:
- Setting profile: how high does the stone sit?
- Clasp and closure: what kind, and how large?
- Hallmarks: is the metal stamp visible?
- Scale: on a hand, neck, or ear, or beside a ruler.
- Stone detail: a close view of the gemstone or diamond.
Clear imagery also shapes what happens after the sale. Another category has written about the link between accurate visuals and returns, in this playbook on reducing e-commerce returns. The product differs from jewelry, but the principle of showing shoppers what they will actually receive carries over.
Write alt text as a description of what is in the photo: “14k yellow gold bezel-set diamond solitaire pendant, front view.” It serves accessibility and search, and a feed can carry it as a label.
Variant imagery for configurable jewelry
Rings rarely come in one version. A shopper picks a metal, a stone, or a style, and the gallery should follow. Adobe’s GraphQL guidance for configurable products shows that the media gallery of a configurable product can change after a shopper selects an option.
So test it. For each collection:
- Pick one configurable product and select every metal option in turn.
- Confirm the first image changes to the matching metal, not a generic parent photo.
- Repeat for stone or style options.
- Check the mobile product page, not just desktop.
- Confirm nothing hidden at store-view level removes a needed angle.
If the supplier supplies only one metal photo, decide up front whether to show it with a note or hold the other options back. Shoppers rarely forgive a yellow-gold photo that arrives as rose gold.
Why a blank gallery after import is often just queues
Media handling in Magento is asynchronous. Adobe’s message queue documentation lists three consumers that matter here:
-
media.gallery.synchronizationimports image files into themedia_gallery_assetdatabase table. -
media.content.synchronizationassigns media links to products, categories, CMS blocks, and pages, and removes unused assets. -
media.gallery.renditions.updategenerates and validates media paths and resized copies.
A successful API response does not by itself prove all three have finished. If your staff see an empty gallery or a stale thumbnail an hour after a supplier update, that is not necessarily missing inventory. Ask your developer to confirm the consumers are running, then check each stage separately: file received, gallery synchronized, content linked, renditions complete.
If you run a feed pipeline, report those states separately. It turns “the images are broken” into a specific, fixable step.
Preventing duplicate images when feeds sync
Supplier feeds repeat. The same product arrives every night, and that is where duplication hides. Adobe documents a WebAPI issue, ACP2E-3789, in which a product update that retains media without preserving the expected media ID creates a newly named duplicate file instead of replacing the existing one. It applies to Adobe Commerce 2.4.5 to 2.4.8 and is listed as scheduled for inclusion in 2.4.9. Adobe’s advice is to verify the patch on affected versions and monitor pub/media/catalog/products/cache for unintended buildup.
Whatever your version, build the feed logic around these habits:
- Match by stable identifier or controlled filename, such as SKU plus view plus variant code.
- Update in place rather than re-adding.
- Retire removed assets explicitly when a supplier drops an image.
- Audit the media folder size monthly during the first quarter after launch.
If you import images in bulk from CSV, Adobe’s guidance on batch import is the right starting point. The same identity rules apply there.
Video in the gallery and on the page
Jewelry moves, and video shows sparkle in a way stills do not. Adobe’s ProductGallery storefront component supports thumbnails, zoom-related configuration, sizing parameters, and optional product video. Video is disabled by default in the documented component and can be enabled by configuration. It can be positioned before or after static images.
For campaign pages, Page Builder’s slider can use an uploaded or existing gallery image. A video background can use YouTube, Vimeo, or a valid video-file URL such as MP4. Page Builder also documents lazy loading for video and a fallback image, so a hero clip does not hold up first render.
Not every clip qualifies as a useful product video. We cover what to include in a feed in What Counts as a Jewelry Product Video for Feeds.
Our perspective: treat the catalog as a living thing
We work with product data every day, and one pattern repeats. Retailers treat images as a launch task: upload, publish, move on. But a jewelry catalog changes constantly. Vendors add pieces, retire styles, reshoot hero images, and change metals. An image policy that worked for 300 SKUs breaks at 30,000.
So we suggest three habits.
Decide your source of truth. When a supplier updates a photo, should it overwrite yours? Choose by field and by vendor, and write it down.
Keep structure ahead of pictures. Images attach to products, and products attach to clean attributes. If metal, stone, and shape are inconsistent, variant imagery will be too. That is why we wrote about GIA-aligned Magento jewelry attributes and layered navigation setup.
Watch the pipeline, not just the page. A tidy gallery is the result of file receipt, linking, and renditions all finishing. Monitor those, and surprises get rare.
The gallery is a platform capability, not a governance process. Naming conventions, rights metadata, store-view rules, and variant mapping are still yours to define. We would rather you spend an afternoon on that than a month cleaning up.
— Anthony
A practical workflow for supplier imagery
Here is a sequence you can adapt this quarter.
- Inventory what you have. Export a list of products with image counts. Flag any with a single image.
- Define the naming convention. For example, SKU, view, and variant code.
- Set role rules. Which view is Base, Small, Thumbnail, and Swatch for each product type.
- Separate content from product media. Banners and guides in the CMS gallery; product photography on products.
- Pilot one vendor. Import a single collection, confirm queues finish, and test variants.
- Check duplicates. Compare file counts in the media folder before and after a second sync.
- Roll out by vendor. Add the rest once the pilot stays clean for two sync cycles.
For the wider context of structuring a wholesale catalog, see our guides on jewelry ecommerce catalog management and launching a wholesale Magento jewelry catalog.
Where JewelCloud fits
If your goal is to expand your assortment without carrying physical stock, the image workload multiplies fast. The JewelCloud Product Feed gives retailers structured, standardized jewelry product data from participating vendors, built for the specifics of jewelry rather than generic merchandise. If you are rebuilding the storefront around it, our web design for jewelers service is the next step. Suppliers who want to distribute catalogs to retailers can look at the Silver vendor membership, listed at $1,500 per month.
FAQ
Where do I find the media gallery in Magento 2?
Go to Content > Media > Media Gallery in the Admin. If you only see the older file browser, enable the enhanced version under Stores > Settings > Configuration > Advanced > System > Media Gallery by setting Enable Old Media Gallery to No. Save and refresh the invalid cache types.
Is the media gallery the same as a product’s Images and Videos section?
No. The CMS gallery manages reusable assets for pages, blocks, and categories. Product media entries carry roles, position, visibility, labels, and media type, and you manage them on each product.
Why are my newly uploaded images not showing in the gallery?
The most common cause is a queue or cache problem. Media processing uses consumers such as media.gallery.synchronization, and a completed upload does not guarantee they have finished. Have your developer check the consumers, then refresh the cache. Some Magento versions also have reported bugs, so check Adobe’s release notes for your exact version.
How do I stop supplier feeds from duplicating product images?
Match existing images by a stable identifier or controlled filename, update them in place, and retire removed images explicitly. If you use WebAPI updates on Adobe Commerce 2.4.5 to 2.4.8, check whether patch ACP2E-3789 applies to you.
Can I show video on jewelry product pages?
Yes. Adobe’s storefront product gallery component supports optional product video, which is off by default and enabled through configuration. Make sure clips load without blocking the page.
Sources
- The Media Gallery, Adobe Commerce
- Media Gallery Asset Management, Magento merchdocs
- Manage product images and videos, Adobe Commerce
- Configurable product data types, Adobe Commerce
- Message queue consumers, Adobe Commerce
- ACP2E-3789: Media files duplicated on product update via WebAPI
- ProductGallery, Adobe Commerce Storefront
- Media - Slider, Adobe Commerce