Skip to main content

​
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.
  3. Default selected options — If defaultSelectedOptions is specified, the first matching variant is returned.
  4. Vector search match — If semantic search matched a specific variant embedding, that variant is returned.
  5. 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, and accessing variant-specific metafields. See Keyword-matched variant selection for more details.

​
Variant schema fields

Field NameTypeDescription
idIntegerUnique identifier for the variant
titleStringTitle of the variant (typically the option values combined)
priceStringPrice of the variant
skuStringSKU of the variant
compare_at_priceStringCompare at price of the variant (original price before discount)
availableBooleanAvailability status of the variant. Calculation can be configured at the store level. See Variant Availability Calculation for details.
in_stock_location_idsArray of IntegersSort-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.
positionIntegerPosition of the variant in the product’s variant list
selected_optionsArray of ObjectsThe selected options for this variant (e.g., Size: “M”, Color: “Blue”)
featured_mediaObjectThe featured media for this variant (if variant-specific media exists)
created_atDateTimeDateTime when the variant was created
updated_atDateTimeDateTime when the variant was last updated
requires_selling_planBooleanWhether the variant requires a selling plan (subscription)
has_selling_planBooleanWhether the variant has an associated selling plan
inventory_quantityIntegerTotal inventory quantity across all locations (only included when Expose Variant Inventory is enabled)
inventory_policyStringInventory policy for the variant: DENY (stop selling when out of stock) or CONTINUE (allow overselling). Only included when Expose Variant Inventory is enabled.
inventory_levelsObjectObject 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, not 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, such as building a variant selector with all sizes and colors, showing a complete price range across all variants, or creating custom product comparison interfaces. This attribute is particularly useful for product detail pages where customers need to see all available options.

​
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.
Featurefirst_or_matched_variantvariants
Return TypeSingle variant objectArray of variant objects
Use CaseDisplay matched/default variantDisplay all available variants
OrderingN/A (single variant)Ordered by position
FieldsVariant schema fieldsSame 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 NameTypeDescription
idIntegerUnique identifier for the variant
titleStringTitle of the variant (typically the option values combined)
priceStringPrice of the variant (includes discount entitlements when applicable)
skuStringSKU of the variant
compare_at_priceStringCompare at price of the variant (original price before discount)
availableBooleanAvailability status of the variant
in_stock_location_idsArray of IntegersSort-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.
positionIntegerPosition of the variant in the product’s variant list
selected_optionsArray of ObjectsThe selected options for this variant (e.g., Size: “M”, Color: “Blue”)
featured_mediaObjectThe featured media for this variant (if variant-specific media exists)
created_atDateTimeDateTime when the variant was created
updated_atDateTimeDateTime when the variant was last updated
requires_selling_planBooleanWhether the variant requires a selling plan (subscription)
has_selling_planBooleanWhether the variant has an associated selling plan
inventory_quantityIntegerTotal inventory quantity across all locations (only included when Expose Variant Inventory is enabled)
inventory_policyStringInventory policy for the variant: DENY (stop selling when out of stock) or CONTINUE (allow overselling). Only included when Expose Variant Inventory is enabled.
inventory_levelsObjectObject 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 NameTypeDescription
nameStringThe option name (e.g., “Color”, “Size”)
codeStringA normalized, URL-friendly version of the option name (e.g., “color”, “size”)
valuesArray of ObjectsArray of unique option values with their associated swatch and metafield data

​
Option value schema fields

Field NameTypeDescription
valueStringThe option value (e.g., “Red”, “Medium”)
swatchObject or nullSwatch data containing color and/or image information
linked_metafield_valueMixed or nullThe linked metafield value associated with this option value in Shopify

​
Swatch object schema

Field NameTypeDescription
colorString or nullHex color code (e.g., “#FF0000”)
imageObject or nullImage 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"
}

​
See also