Improved Keyword Match Resolution for Variant Options
Search results now show the most relevant variant.
When keyword features target variant-scoped attributes — such as options, variant metafields, or variant fields like SKU — the system now automatically identifies the variant with the highest keyword relevance for each product. The first_or_matched_variant field in the API response reflects this best-matching variant rather than defaulting to the first variant by position.
For example, if you have a keyword weight on options.material and a customer searches for "Canvas," each product's response will include the "Canvas" variant as the matched variant, showing the correct price and availability for that size.
The full variant selection priority is now:
- Explicit variant filters
- Keyword-matched variant (new)
- Pin-level default variant options
- Request-level default selected options
- Vector search match
- Position fallback
Keyword-matched variant selection applies to text searches where keyword features are configured on variant-scoped attributes. It does not apply to browse, image search, or similar product requests.