> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Variant & Option Data
> Understand variant-level data fields including first_or_matched_variant, the full variants array, and the enhanced options_v2 structure.
## Variant data with first\_or\_matched\_variant
The `first_or_matched_variant` field provides variant-level data in search and browse responses. This field is particularly useful when you need to display variant-specific information like the matched variant's price, SKU, or selected options.
### When to use first\_or\_matched\_variant
This field returns the most relevant variant for the current request. The system selects a variant using the following priority:
1. **Explicit variant filters** — If option or variant filters are applied, the filtered variant is returned.
2. **Keyword-matched variant** — During text search, if keyword features target variant-scoped attributes (options, variant metafields, or variant fields), the variant with the highest keyword relevance score is returned. To prevent false matches, variant selection requires keyword scores to exceed a minimum relevance threshold — only variants with meaningful keyword relevance are selected.
3. **Pin-level default variant** — If the product is pinned (via a merchandising rule or a ranking rule) and the pin has default variant options configured, the variant matching those options is returned. See [default variant for pins](/platform/ranking-relevancy#default-variant-for-pins).
4. **Default selected options** — If `defaultSelectedOptions` is specified, the first matching variant is returned.
5. **Confident vector search match** — If semantic search matched a specific variant embedding and the match is confident, that variant is returned. Confidence is determined by comparing the variant embedding distance against the product-level embedding distance of the same type (text-to-text or image-to-image). A match is confident when the variant is meaningfully closer to the query than the product-level embedding. When multiple variants have similar vector scores, or when no product-level embedding of the same type exists for comparison, the system falls through to the position fallback.
6. **Position fallback** — The first available variant by position is returned.
Common use cases include:
* Displaying the correct variant image when filtering by color
* Showing the matched variant's price when filtering by size
* Surfacing the keyword-relevant variant when searching for a specific option value
* Accessing variant-specific metafields
See [Keyword-matched variant selection](/platform/ranking-relevancy#keyword-matched-variant-selection) for more details.
### Variant schema fields
| Field Name | Type | Description |
| :----------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | Integer | Unique identifier for the variant |
| title | String | Title of the variant (typically the option values combined) |
| price | String | Price of the variant |
| sku | String | SKU of the variant |
| compare\_at\_price | String | Compare at price of the variant (original price before discount) |
| available | Boolean | Availability status of the variant. Calculation can be configured at the store level. See [Variant Availability Calculation](/shopify-integration/catalog-sync#variant-availability-calculation) for details. |
| in\_stock\_location\_ids | Array of Integers | **Sort-only field.** Array of location IDs where the variant has available inventory (available > 0). This field can be used in sort orders for location-based product demotion but is not filterable and is not included in API responses. |
| position | Integer | Position of the variant in the product's variant list |
| selected\_options | Array of Objects | The selected options for this variant (e.g., Size: "M", Color: "Blue") |
| featured\_media | Object | The featured media for this variant (if variant-specific media exists) |
| created\_at | DateTime | DateTime when the variant was created |
| updated\_at | DateTime | DateTime when the variant was last updated |
| requires\_selling\_plan | Boolean | Whether the variant requires a selling plan (subscription) |
| has\_selling\_plan | Boolean | Whether the variant has an associated selling plan |
| inventory\_quantity | Integer | Total inventory quantity across all locations (only included when Expose Variant Inventory is enabled) |
| inventory\_policy | String | Inventory policy for the variant: `DENY` (stop selling when out of stock) or `CONTINUE` (allow overselling). Only included when Expose Variant Inventory is enabled. |
| inventory\_levels | Object | Object mapping location IDs to available inventory quantities (e.g., `{"1001": 5, "1002": 10}`). Returns empty object `{}` when no inventory data exists. Only included when Expose Variant Inventory is enabled. |
The `inventory_quantity`, `inventory_policy`, and `inventory_levels` fields only appear in variant data when the store has the Expose Variant Inventory setting enabled. Location IDs in `inventory_levels` are returned as string keys.
### Example first\_or\_matched\_variant response
```json theme={null}
{
"first_or_matched_variant": {
"id": 41234567890123,
"title": "Medium / Blue",
"price": "49.99",
"sku": "TSHIRT-BLU-M",
"compare_at_price": "59.99",
"available": true,
"position": 2,
"selected_options": [
{
"name": "Size",
"value": "Medium"
},
{
"name": "Color",
"value": "Blue"
}
],
"featured_media": {
"alt": "Blue T-Shirt",
"src": "https://cdn.shopify.com/s/files/variant-image.jpg",
"width": 800,
"height": 800,
"mediaContentType": "IMAGE"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-03-20T14:45:00.000000Z",
"requires_selling_plan": false,
"has_selling_plan": false,
"inventory_quantity": 15,
"inventory_policy": "DENY",
"inventory_levels": {
"1001": 5,
"1002": 10
}
}
}
```
To include `first_or_matched_variant` in API responses, you must explicitly request it in the `attributes` array parameter. See the [Available Attributes for API Requests](/developers/product-schema/api-attributes) section.
When combining `price_range` with option filters in search or browse operations, be aware that `price_range.from` and `price_range.to` represent the minimum and maximum prices across all variants of a product. They do not reflect the price of the variant matching your selected options. For accurate price-based sorting and filtering with option filters, use `variants.price` instead, which will automatically select the appropriate variant based on applied filters.
## All variants with variants
The `variants` attribute provides access to all product variants in a single API response. This field returns an array of all variants for a product, ordered by position, making it ideal for displaying complete variant selection interfaces or building custom product pages.
### When to use variants
Use the `variants` attribute when you need to display all available options for a product at once — for example, building a variant selector with all sizes and colors, showing a complete price range, or creating custom comparison interfaces. This attribute is particularly useful for product detail pages.
### How variants differs from first\_or\_matched\_variant
While `first_or_matched_variant` returns a single variant (either the first available or the one matching applied filters), the `variants` attribute returns **all variants** for the product as an array. Both attributes return the same field structure for each variant, but `variants` gives you complete visibility into all product options.
| Feature | first\_or\_matched\_variant | variants |
| :---------- | :------------------------------ | :----------------------------- |
| Return Type | Single variant object | Array of variant objects |
| Use Case | Display matched/default variant | Display all available variants |
| Ordering | N/A (single variant) | Ordered by position |
| Fields | Variant schema fields | Same variant schema fields |
### Variants array structure
The `variants` attribute returns an array of variant objects, each containing the same fields as `first_or_matched_variant`:
| Field Name | Type | Description |
| :----------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | Integer | Unique identifier for the variant |
| title | String | Title of the variant (typically the option values combined) |
| price | String | Price of the variant (includes discount entitlements when applicable) |
| sku | String | SKU of the variant |
| compare\_at\_price | String | Compare at price of the variant (original price before discount) |
| available | Boolean | Availability status of the variant |
| in\_stock\_location\_ids | Array of Integers | **Sort-only field.** Array of location IDs where the variant has available inventory (available > 0). This field can be used in sort orders for location-based product demotion but is not filterable and is not included in API responses. |
| position | Integer | Position of the variant in the product's variant list |
| selected\_options | Array of Objects | The selected options for this variant (e.g., Size: "M", Color: "Blue") |
| featured\_media | Object | The featured media for this variant (if variant-specific media exists) |
| created\_at | DateTime | DateTime when the variant was created |
| updated\_at | DateTime | DateTime when the variant was last updated |
| requires\_selling\_plan | Boolean | Whether the variant requires a selling plan (subscription) |
| has\_selling\_plan | Boolean | Whether the variant has an associated selling plan |
| inventory\_quantity | Integer | Total inventory quantity across all locations (only included when Expose Variant Inventory is enabled) |
| inventory\_policy | String | Inventory policy for the variant: `DENY` (stop selling when out of stock) or `CONTINUE` (allow overselling). Only included when Expose Variant Inventory is enabled. |
| inventory\_levels | Object | Object mapping location IDs to available inventory quantities (e.g., `{"1001": 5, "1002": 10}`). Returns empty object `{}` when no inventory data exists. Only included when Expose Variant Inventory is enabled. |
### Example variants response
```json theme={null}
{
"id": 7003338965178,
"title": "Premium Cotton T-Shirt",
"handle": "premium-cotton-t-shirt",
"variants": [
{
"id": 41234567890123,
"title": "Small / Blue",
"price": "29.99",
"sku": "TSHIRT-BLU-S",
"compare_at_price": "39.99",
"available": true,
"position": 1,
"selected_options": [
{
"name": "Size",
"value": "Small"
},
{
"name": "Color",
"value": "Blue"
}
],
"featured_media": {
"alt": "Blue T-Shirt",
"src": "https://cdn.shopify.com/s/files/variant-blue.jpg",
"width": 800,
"height": 800,
"mediaContentType": "IMAGE"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-03-20T14:45:00.000000Z",
"requires_selling_plan": false,
"has_selling_plan": false,
"inventory_quantity": 8,
"inventory_policy": "DENY",
"inventory_levels": {
"1001": 3,
"1002": 5
}
},
{
"id": 41234567890124,
"title": "Medium / Blue",
"price": "29.99",
"sku": "TSHIRT-BLU-M",
"compare_at_price": "39.99",
"available": true,
"position": 2,
"selected_options": [
{
"name": "Size",
"value": "Medium"
},
{
"name": "Color",
"value": "Blue"
}
],
"featured_media": {
"alt": "Blue T-Shirt",
"src": "https://cdn.shopify.com/s/files/variant-blue.jpg",
"width": 800,
"height": 800,
"mediaContentType": "IMAGE"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-03-20T14:45:00.000000Z",
"requires_selling_plan": false,
"has_selling_plan": false,
"inventory_quantity": 15,
"inventory_policy": "DENY",
"inventory_levels": {
"1001": 5,
"1002": 10
}
},
{
"id": 41234567890125,
"title": "Large / Red",
"price": "32.99",
"sku": "TSHIRT-RED-L",
"compare_at_price": "42.99",
"available": true,
"position": 3,
"selected_options": [
{
"name": "Size",
"value": "Large"
},
{
"name": "Color",
"value": "Red"
}
],
"featured_media": {
"alt": "Red T-Shirt",
"src": "https://cdn.shopify.com/s/files/variant-red.jpg",
"width": 800,
"height": 800,
"mediaContentType": "IMAGE"
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-03-20T14:45:00.000000Z",
"requires_selling_plan": false,
"has_selling_plan": false,
"inventory_quantity": 22,
"inventory_policy": "CONTINUE",
"inventory_levels": {
"1001": 12,
"1003": 10
}
}
]
}
```
To include `variants` in API responses, you must explicitly request it in the `attributes` array parameter. The variants array is always ordered by the variant's position field. When discount entitlements are configured, the price field reflects the discounted price for each variant.
## options\_v2 structure
The `options_v2` field provides enhanced option data with swatch and linked metafield information from Shopify's product option values. This field is useful when you need to display visual swatches (colors or images) for product options or access linked metafield data associated with specific option values.
### options\_v2 schema fields
| Field Name | Type | Description |
| :--------- | :--------------- | :---------------------------------------------------------------------------- |
| name | String | The option name (e.g., "Color", "Size") |
| code | String | A normalized, URL-friendly version of the option name (e.g., "color", "size") |
| values | Array of Objects | Array of unique option values with their associated swatch and metafield data |
### Option value schema fields
| Field Name | Type | Description |
| :----------------------- | :------------- | :---------------------------------------------------------------------- |
| value | String | The option value (e.g., "Red", "Medium") |
| swatch | Object or null | Swatch data containing color and/or image information |
| linked\_metafield\_value | Mixed or null | The linked metafield value associated with this option value in Shopify |
### Swatch object schema
| Field Name | Type | Description |
| :--------- | :------------- | :------------------------------------------- |
| color | String or null | Hex color code (e.g., "#FF0000") |
| image | Object or null | Image object with `alt` and `url` properties |
### Example options\_v2 response
```json theme={null}
{
"options_v2": [
{
"name": "Color",
"code": "color",
"values": [
{
"value": "Red",
"swatch": {
"color": "#FF0000",
"image": null
},
"linked_metafield_value": null
},
{
"value": "Blue",
"swatch": {
"color": "#0000FF",
"image": null
},
"linked_metafield_value": null
},
{
"value": "Pattern A",
"swatch": {
"color": null,
"image": {
"alt": "Pattern A swatch",
"url": "https://cdn.shopify.com/s/files/pattern-a.jpg"
}
},
"linked_metafield_value": "organic-cotton-blend"
}
]
},
{
"name": "Size",
"code": "size",
"values": [
{
"value": "Small",
"swatch": null,
"linked_metafield_value": null
},
{
"value": "Medium",
"swatch": null,
"linked_metafield_value": null
},
{
"value": "Large",
"swatch": null,
"linked_metafield_value": null
}
]
}
]
}
```
The `options_v2` field preserves Shopify's option ordering and includes option values from all variants regardless of stock status, aligning with `original_options` behavior. When the same option value appears on multiple variants with different swatch or metafield data, the first non-null value is used.
### Example product (JSON)
```json theme={null}
{
"id": 7002787512506,
"tags": [
"Active22",
"New Arrivals",
"top1",
"topmost"
],
"title": "LOUIS VUITTON\/SUPREME BOX LOGO",
"category": null,
"combined_listing_parent_product_id": null,
"combined_listing_role": null,
"featured_media": {
"alt": "SUPREME T-SHIRT",
"src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0588\/3677\/9194\/products\/supreme_lv_tee_white_2-2.jpg?v=1644024149",
"width": 940,
"height": 627,
"mediaContentType": "IMAGE"
},
"handle": "supreme-t-shirty92wjc8-001",
"images": [
{
"alt": "SUPREME T-SHIRT",
"src": "https:\/\/cdn.shopify.com\/s\/files\/1\/0588\/3677\/9194\/products\/supreme_lv_tee_white_2-2.jpg?v=1644024149",
"width": 940,
"height": 627,
"variant_ids": []
}
],
"vendor": "SUPREME",
"available": true,
"body_html": "The Supreme Louis Vuitton Monogram box logo shirt represents a historic partnership between two fashion giants, boasting meticulous craftsmanship and attention to detail. Crafted from the finest materials, the shirt showcases Louis Vuitton's timeless monogram pattern as the background, with Supreme's unmistakable red box logo boldly and tastefully placed at its center. This unique collaboration item is not just a shirt; it's a symbol of the convergence of streetwear culture and high-end luxury, making it an icon of the fashion world. With limited availability and an aura of exclusivity, it has become a grail for collectors and enthusiasts, embodying a blend of urban style and opulence that continues to captivate fashion-conscious individuals worldwide.",
"created_at": "2022-02-05T01:22:27.000000Z",
"metafields": {
"product": {
"alias": "LOUIS VUITTON MONOGRAM BOX LOGO T-SHIRT",
"colorway": "WHITE",
"condition": "New",
"styleCode": "Y92WJC8-001",
"searchColor": [
"white"
],
"yearOfRelease": "S\/S 2017"
}
},
"named_tags": {
"Datahub": "Synced",
"ColorWay": "WHITE",
"AliasName": "LOUIS VUITTON MONOGRAM BOX LOGO T-SHIRT",
"Condition": "New",
"StyleCode": "Y92WJC8-001",
"Collection": [
"Designer",
"Apparel",
"Louis Vuitton",
"Supreme",
"T-Shirts"
],
"SearchColor": "white",
"YearOfRelease": "S\/S 2017",
"ProductSubType": "T-Shirt",
"SearchKeyword1": "SUPREME\/LOUIS VUITTON MONOGRAM BOX LOGO T-SHIRT",
"SearchKeyword2": "S\/S 2017",
"SearchKeyword3": "WHITE"
},
"updated_at": "2024-04-02T21:31:39.000000Z",
"price_range": {
"to": 1500,
"from": 1500,
"compare_at_price": 0
},
"options": {
"Size": [
"XS",
"S",
"M",
"L",
"XL",
"2XL"
]
},
"product_type": "Apparel",
"published_at": "2022-02-05T01:22:27.000000Z"
}
```
## See also
* [Product Schema](/developers/product-schema)
* [Metafields & References](/developers/product-schema/metafields)
* [Available Attributes for API Requests](/developers/product-schema/api-attributes)