now the ‘image’ field is deprecated in API version 2026-10 for product variants, we really miss some ‘featuredMedia’ new field. This may sound absurd, as we can gather all media elements through the ‘media’ connection. But this implies a really big change when using it in bulk operations.
So far, we could use the deprecated field image, which was included in the variant lines in the jsonl response. However, if we migrate to the ‘media’ connection (as recommended in the doc), the media elements will come in new lines in the jsonl. If we just wont the featured media, as used to be intended when using ‘image’, the complexity grows considerably.
Please could you consider to add some ‘featuredMedia’ field for variants? It already exists for products, it would be exactly the same idea.
I’m happy to help submit some feedback on this change on your behalf internally.
Just to confirm I understand your issue here correctly, you’re concern is specifically with Bulk Operation Queries requesting media on product variants, and returning the media in a separate line item on the JSONL file, due to productVariant.media being a connector, rather than an individual field directly on the productVariant object?
the problem is that, according to the doc, the deprecated field ‘image’ can be replaced by ‘media’. However, this is not a direct change, because ‘image’ is a field and ‘media’ is a connector. This already have a big impact, but this impact makes the complexity grow a lot especially in the bulk operations case.
In the case of products, this is solved with the ‘featuredMedia’ field. I am just asking if having this ‘featureMedia’ also in variants is possible.
I appreciated the added context, I will absolutely be sharing this feedback with our developers internally. While we can’t guarantee that a featuredMedia field on product variants will be added, I can assure you that our developers and product managers do take all our merchant and partner feedback with great value when determining future features and platform changes, and the more feedback we get like this, the more likely a change would be made.
I’ll second this as a problem. Complexities of having to deal with additional line types in the JSONL aside, bulk queries being limited to 5 connections means we have to pick and choose what we need, and if we’re already capped at our 5 on a query now we either need to drop something that might be critical to operations, or implement even more complex workflows to try to join multiple bulk query results/iterative ad-hoc queries together.
Furthermore, there is one derived problem that may cause inconsistency. In a bulk operation, when using the ‘media’ connection and receiving several media elements, how do we know which one is the featured? At Media - GraphQL Admin there is not a field that indicates if a media element is featured or not. We may assume that the featured one is the first one, but in a bulk operation response the elements may come unordered.
There are two related gaps. A singular ProductVariant.featuredMedia field would let apps retrieve the variant’s primary media as one object instead of parsing a connection. Separately, adding query: "media_type:IMAGE" to ProductVariant.media would let apps request an actual image rather than potentially receiving another media type. Product already supports both patterns.
media(first: 1) currently doesn’t fully cover either case because it remains a connection and doesn’t constrain the returned media type, as you noted. I’m checking internally whether either capability can be considered for ProductVariant. I don’t have a confirmed change or timeline to share, but I’ll update this thread if that changes.
I’ve confirmed that a variant can currently have only one media item, and it must be an image. That means media(first: 1) will return the variant image without any filtering required. The media` field is a connection, but you can rely on its first result for this use case currently.
Support for multiple media per variant is something we’ve considered, though I don’t have a guarantee or timeline to share. If that capability is added, adding featuredMedia alongside it is also something being considered. I’ve made sure your feedback was heard by the team.
Being able to use media(first: 1) on a Variant and knowing it always returns an image would solve our problem, and we can replace the deprecated calls.
However, the documentation does not make that clear, so I’m hesitant to make this change and risk something breaking suddenly if this changes retroactively. For example, see the attached screenshot. It makes it seem like one can expect a media to be any of those types.
Can the behaviour you described be specified in the documentation, so we have a “firm” record of this behaviour?
Also, now that I look at it closer, maybe we should be using media.preview.image which would take care of displaying an image regardless of the media type.
I’ve confirmed that a variant can currently have only one media item, and it must be an image. That means media(first: 1) will return the variant image without any filtering required
That’s ok, but then, why adding complexity with a connection?
If that capability is added, adding featuredMedia alongside it is also something being considered
That would be great. When thinking about bulk operations, adding a connection for a single property adds a lot of complexity, moving media data to new entities (and then new lines in the response file). Keeping the featured image inside variant entity would make it much easier.
I can confirm that any future support for multiple media per variant won’t be introduced as a retroactive breaking change. It will be communicated and rolled out carefully, and the first item in ProductVariant.media will remain the featured variant media for the foreseeable future.
Using preview { image { ... } } is also fine. Keep in mind that preview.image can be null until its status is READY: MediaPreviewImage - GraphQL Admin
This doesn’t remove the connection shape or the extra JSONL records you called out for bulk operations. I’ve shared that specific feedback with the team. I don’t have a confirmed change or timeline for adding ProductVariant.featuredMedia and I’ll update this thread if anything changes on that front.
