The Catalog API now returns video and 3D model media on products that have it, and supports filtering search results by media type. You can request only products that have video or 3D model media attached, and matching products return links to those assets in the same response. The new filter is optional, and existing queries keep returning the same products.
What changed
, , and now return video and 3D model assets on a product's media array. Previously it carried images only.
Catalog API search accepts a new filter, catalog.filters.media. Each entry names a media type: image, video, or . Entries combine with AND, so asking for video and returns only products that have both.
An unrecognized type doesn't fail the request. The API ignores it and reports it in result.messages[] with the code .
Products that match come back with media asset URLs, so a client can render a product without a second request to fetch its media.
Previously you had to request products, inspect each one for usable media, and discard products that didn't have any. The new filter replaces that pattern. There's no change to existing filters, no new endpoint, and no migration.
The new media types require the draft version of the Shopify global Catalog extension(dev.shopify.catalog.global). Declaring draft is a one line change in your agent profile. Without it, the media field returns images only. The draft schema moves to stable in the next UCP release.
Filtering by media type applies to . The asset URLs also return on and , even if you don't filter. Filter on the stableextension version and the filter is honored, but the response carries images only.
Filtering by media type applies to . The asset URLs also return on and , even if you don't filter. Filter on the stableextension version and the filter is honored, but the response carries images only.
Note: <strong></strong> Filtering by media type applies to <code><span class="PreventFireFoxApplyingGapToWBR">search<wbr/>_catalog</span></code>. The asset URLs also return on <code><span class="PreventFireFoxApplyingGapToWBR">get<wbr/>_product</span></code> and <code><span class="PreventFireFoxApplyingGapToWBR">lookup<wbr/>_catalog</span></code>, even if you don't filter. Filter on the stableextension version and the filter is honored, but the response carries images only.
Who's affected
This change affects apps and tools that call the Catalog API and:
- Use
and want to filter products byimage,video, ormedia - Rely on product media asset URLs in
,, orresponses
To receive video and 3D model assets, your client must declare the draft version of the Shopify global Catalog extension (dev.shopify.catalog.global) in its agent profile. Without it, the media field continues to return images only.
Why this matters
If you're building augmented reality try-on, 3D product viewers, or camera-first shopping, you can't use a product without a renderable asset. Filtering for products with specificmedia at query time removes the fetch, inspect, and discard loop, and returning asset URLs in the same response removes an extra round trip per product.
What to do
No action is required if you don't need video or 3D media in catalog results. Existingqueries keep working and return the same products.
- Declare the draft version of
dev.shopify.catalog.globalin your agent profile, or point at the draft profile Shopify publishes. - Add
catalog.filters.mediato yourrequest with the media types you need. - Read the asset URLs off the media array in the response. Video and 3D entries carry a
sourcesarray with one entry per file format. - Handle products where the media you asked for is present but the format you need isn't.
- Confirm it worked by checking that every returned product includes at least one asset URLof the requested type. Images only means your profile is still on the stable version.