Executive summary
- What: The Catalog API now returns video and 3D model assets on product media and accepts a new optional filter, catalog.filters.media, on search_catalog requests.
- Why: Clients building agent-driven or immersive shopping surfaces can request only products that carry renderable media, instead of fetching broadly and discarding what does not qualify.
- Who: Teams building against the Catalog API for agentic commerce, 3D viewers, or AR try-on, plus Plus merchants whose product media investment needs to be discoverable.
What changed
Three Catalog operations now carry richer media. search_catalog, get_product, and lookup_catalog return video and 3D model assets in a media array that previously held images only. Video and 3D entries include a sources array with one entry per file format.
Search also accepts a new optional filter. Each entry in catalog.filters.media names a type of image, video, or model_3d, and entries combine with AND, so requesting both returns only products that carry both. An unrecognised type does not fail the call. The API ignores it and reports it in result.messages with a not_found code, so a typo quietly widens your result set rather than erroring.
There is one gate. The new media types require the draft version of the Shopify global Catalog extension, dev.shopify.catalog.global, declared in your agent profile. Without it the media field keeps returning images only, and a filter against the stable version is honoured but still yields image-only responses. The draft schema moves to stable in the next UCP release. Existing queries are unaffected, with no new endpoint and no migration.
Why it matters
For merchants who have invested in 3D and video production, the constraint has never been creating the assets. It has been that downstream surfaces could not cheaply tell which products had them. The old pattern was to request a page of products, inspect each one, discard those without usable media, and repeat. That loop is expensive in latency and API budget, and it degrades exactly when a catalogue is large and media coverage is partial, which describes most enterprise catalogues.
Filtering at query time removes the loop, and inline asset URLs remove a second round trip per product. For a merchandiser, that turns rich media into something an agent or a 3D surface can reliably select on. If you are scoping how media coverage maps to your merchandising surfaces, our team can help frame the audit.
Role-specific impact
- Marketers: media coverage becomes a targetable attribute. Products with video or 3D can be surfaced deliberately in agent-driven discovery, giving a measurable reason to prioritise asset production for specific lines.
- Developers: add the draft extension declaration to the agent profile first, then add the filter. Handle the case where the requested media type is present but the specific file format you need is not.
- Store admins: media completeness now has a direct visibility consequence. Products missing video or 3D can be excluded from surfaces that filter on it, so asset gaps are worth tracking as a catalogue quality metric.
Use-case example
Real-world scenario
A furniture retailer with 9,000 SKUs has 3D models on roughly 1,100 of them, concentrated in seating and tables. Their AR room-planner pulled products in pages of 50 and discarded any without a model, averaging close to nine requests to fill a single 40-item planner shelf. Filtering on model_3d at query time reduced that to one request, and because asset URLs return inline, the client stopped issuing a follow-up media lookup per product. The result was roughly 90 percent fewer Catalog calls per planner session.
Implementation checklist
- Declare the draft version of dev.shopify.catalog.global in your agent profile, or point at the draft profile fixture Shopify publishes.
- Add catalog.filters.media to your search_catalog request with the media types you need, remembering that multiple entries combine with AND.
- Read asset URLs from the media array in the response rather than issuing a separate media request per product.
- Handle products where the requested media type exists but the file format your client needs is absent from the sources array.
- Verify the profile took effect by confirming returned products carry an asset of the requested type. Image-only responses mean you are still on the stable version.
FAQ
Q: Will adding this filter change the results of our existing queries?
A: No. The filter is optional and existing queries return the same products. The only change without it is that media arrays can include video and 3D entries, and only once your profile declares the draft extension.
Q: What happens if we send a media type the API does not recognise?
A: The request still succeeds. The unrecognised type is ignored and reported in result.messages with a not_found code, so check that array during development rather than assuming a silent pass means the filter applied.
Resources
Need guidance? Talk to Makro.