Variant & Option Data

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:

Explicit variant filters — If option or variant filters are applied, the filtered variant is returned.
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.
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.
Default selected options — If defaultSelectedOptions is specified, the first matching variant is returned.
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.
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 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 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). Variants with inventory tracking disabled in Shopify are always reported as `CONTINUE`. 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

{
  "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 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). Variants with inventory tracking disabled in Shopify are always reported as `CONTINUE`. 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

{
  "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

{
  "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)

{
  "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"
}

Overview

Metafields

Variant & Option Data

Variant data with first_or_matched_variant

When to use first_or_matched_variant

Variant schema fields

Example first_or_matched_variant response

All variants with variants

When to use variants

How variants differs from first_or_matched_variant

Variants array structure

Example variants response

options_v2 structure

options_v2 schema fields

Option value schema fields

Swatch object schema

Example options_v2 response

Example product (JSON)

See also

​Variant data with first_or_matched_variant

​When to use first_or_matched_variant

​Variant schema fields

​Example first_or_matched_variant response

​All variants with variants

​When to use variants

​How variants differs from first_or_matched_variant

​Variants array structure

​Example variants response

​options_v2 structure

​options_v2 schema fields

​Option value schema fields

​Swatch object schema

​Example options_v2 response

​Example product (JSON)

​See also

Variant data with first_or_matched_variant

When to use first_or_matched_variant

Variant schema fields

Example first_or_matched_variant response

All variants with variants

When to use variants

How variants differs from first_or_matched_variant

Variants array structure

Example variants response

options_v2 structure

options_v2 schema fields

Option value schema fields

Swatch object schema

Example options_v2 response

Example product (JSON)

See also