Skip to main content

​
Product Schema Overview

The product schema is a standardized format that transforms your Shopify product data into an optimized structure for the search and browse engine.

​
Schema Fields

The following table outlines the key fields in the product schema, along with their data types, descriptions, and example values:
Field NameTypeDescriptionExample Value
idIntegerUnique identifier for the product7003338965178
titleStringTitle of the product"SUPREME SEALLINE SEE POUCH SMALL"
body_htmlStringHTML content describing the product"The Supreme Sealline See Pouch Small is a versatile and..."
vendorStringThe product’s vendor"SUPREME"
product_typeStringType of the product"Accessories"
created_atDateTimeDateTime when the product was created1644047925
handleStringA unique human-friendly string for the product, used in the product’s URL"supreme-pouch-44370ss18a32-sm"
categoryObjectThe category of a product from Shopify’s Standard Product Taxonomy{"id": "gid://shopify/TaxonomyCategory/aa-1", "name": "Clothing", "is_leaf": false, "is_root": false, "full_name": "Apparel & Accessories > Clothing"}
combined_listing_parent_product_idInteger7003338965178
combined_listing_roleStringPARENT
featured_mediaObjectThe featured media.{"alt": "The top and bottom view of a snowboard. The top has view is turquoise and black with graphics of\n trees. The bottom view is turquoise with the word hydrogen written in cursive.", "src": "https://cdn.shopify.com/s/files/1/0630/8265/9999/files/Main.jpg?v=1736281499", "width": 1600, "height": 1600, "mediaContentType": "IMAGE"}
updated_atDateTimeDateTime when the product was last updated1698280024
published_atDateTimeDateTime when the product was published1644047925
tagsArray of StringsTags associated with the product["Collection: Best Seller", "Collection:Accessories", "Collection:Supreme Accessories"]
imagesArray of ObjectsImages related to the product.[{"alt": "SUPREME POUCH", "src": "https://cdn.shopify.com/", "width": 800, "height": 534, "variant_ids": []}]
metafieldsObjectConfigured metafields for the product{"product": {"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK", "styleCode": "SS18A30 BLACK", "yearOfRelease": 2018}}
availableBooleanAvailability status of the producttrue
is_gift_cardBooleanWhether the product is a gift cardfalse
has_variants_that_require_componentsBooleanWhether the product has variants that require bundle components (used for bundle products)false
price_rangeObjectPrice range of the product, including from and to fields{"from": 7.97, "to": 7.97, "compare_at_price": 7.97}
optionsObjectDynamically created object from product options (can be an array of any type, depending on the product configuration). The key is case-sensisitive.{"Size": ["S", "M", "L"]}
original_optionsObjectDynamically created object from product options (can be an array of any type, depending on the product configuration). The key is case-sensisitive. This set of options is unfiltered.{"Size": ["S", "M", "L"]}
named_tagsObjectDynamically created object of ‘key:value’ tags on the product. Keys/values in this object are not included in the tags array{"YearOfRelease": 2016}
calculatedObjectCalculated attributes defined in the Layers dashboard. Contains dynamic values computed via JSONLogic formulas{"sku_coverage": 0.85, "days_available": 30}
You can provide type-hints to Named Tags by using the {key}:{type}:{value} tag format. Supported types: number, boolean, and date.

​
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 either the first available variant (based on your out-of-stock settings) or the variant that matches the applied filters or search query. Common use cases include displaying the correct variant image when filtering by color, showing the matched variant’s price when filtering by size, and accessing variant-specific metafields.

​
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
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

​
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
  }
}
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 below.
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.

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

​
Data Types and Formatting

  • Integer: Whole numbers without decimals.
  • String: Textual data, often used for titles or descriptions.
  • Decimal: Numbers with decimal points, typically used for prices.
  • Array: A list of values, used for tags or features.
  • Boolean: A true or false value, indicating binary states such as availability.

​
Supported Metafield Types

The product schema supports various Shopify metafield data types, ensuring that your product data is handled correctly for display and filtering purposes. The following metafield types are currently supported:
TypeDescriptionExample
single_line_text_fieldA single line of text used for titles, names, or other short descriptions."Limited Edition"
multi_line_text_fieldMultiple lines of text, typically used for long descriptions or instructions."Care instructions: Machine wash cold, tumble dry low."
booleanTrue or false value indicating binary states such as availability or inclusion.true
number_integerWhole numbers used for inventory counts, order limits, or other quantities.150
number_decimalNumbers with decimal places, often used for prices, weights, or measurements.29.99
jsonJSON objects used to store structured data such as configurations, specifications, or dynamic content.{"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK"}
dateDate values formatted as YYYY-MM-DD, often used for production dates, release dates, or promotional periods."2023-09-30"
date_timeDateTime values formatted as ISO 8601, used for time-based events like product launches or sales end times."2024-01-01T00:00:00.000Z"
colorColor values formatted as hexadecimal strings, used for product colors or UI elements."#FF5733"
file_referenceLinks to file assets, including images, PDFs, or other documents that can be referenced in product displays or additional resources."https://cdn.shopify.com/files/myfile.pdf"
product_referenceLinks to other product IDs, allowing cross-referencing of related items."gid://shopify/Product/123456789"
variant_referenceReferences to specific product variants, allowing differentiation between product options like size or color."gid://shopify/ProductVariant/987654321"
collection_referenceReferences to collections, used for categorization and dynamic grouping of products."gid://shopify/Collection/456789123"
page_referenceLinks to Shopify pages, typically used for additional information or storytelling about a product."gid://shopify/Page/654321987"
metaobject_referenceReferences to custom metaobjects that can extend product data with additional attributes or structured information."gid://shopify/Metaobject/321654987"
urlURLs pointing to external resources, used for additional product details or external documentation."https://example.com/extended-warranty"
These metafield types allow for greater flexibility and precision when configuring and displaying product data within your search and browse engine.

​
Special Metafields for Layers Features

​
Automatic Sequence Creation

Layers supports automatic sequence creation through a special metafield configuration:
  • Namespace: layers
  • Key: global_sequence
  • Type: list.product_reference
When this metafield is present on products, Layers will automatically create global sequences during bulk data synchronization. The metafield value should contain an array of product references that should be grouped together in the sequence.
This feature is currently in beta and only processes during bulk operations, not during incremental product updates.

​
Metaobject & Reference Handling

The schema supports reference types (e.g., product_reference, variant_reference, collection_reference, metaobject_reference) by capturing only the ID for these references. This ensures optimized storage and lookup during search and browse operations. For a complete list of supported types and their properties, please refer to the official Shopify Metafield Data Types documentation.

​
Metafield Structure and Examples

Metafields are organized by namespace and key in a nested object structure. The namespace groups related metafields together, and each key within a namespace contains the metafield value.

​
Metafield Structure

{
  "metafields": {
    "{namespace}": {
      "{key}": "{value}"
    }
  }
}

​
Example: Custom Product Metafields

{
  "metafields": {
    "custom": {
      "material": "100% Organic Cotton",
      "care_instructions": "Machine wash cold, tumble dry low",
      "country_of_origin": "USA",
      "weight_kg": 0.25
    },
    "product": {
      "colorway": "Midnight Blue",
      "style_code": "SS24-TSHIRT-001",
      "release_date": "2024-03-15",
      "is_limited_edition": true
    },
    "seo": {
      "meta_title": "Premium Organic Cotton T-Shirt | Brand Name",
      "meta_description": "Shop our premium organic cotton t-shirt..."
    }
  }
}

​
Accessing Metafields in Attributes

To create a catalog attribute from a metafield, use dot notation with the full path:
Metafield PathAttribute Code
metafields.custom.materialmetafields.custom.material
metafields.product.colorwaymetafields.product.colorway
metafields.seo.meta_titlemetafields.seo.meta_title

​
Example: List-Type Metafields

List metafields (e.g., list.single_line_text_field, list.product_reference) are stored as arrays: 
{
  "metafields": {
    "custom": {
      "related_colors": ["Red", "Blue", "Green"],
      "compatible_products": [7003338965178, 7003338965179, 7003338965180],
      "size_chart": [
        {"size": "S", "chest": 36, "length": 27},
        {"size": "M", "chest": 38, "length": 28},
        {"size": "L", "chest": 40, "length": 29}
      ]
    }
  }
}

​
Available Attributes for API Requests

When making requests to the Search or Browse API, you can use the attributes parameter to specify which product fields to include in the response. This allows you to optimize response payload size by requesting only the data you need.

​
Core Product Attributes

The following attributes are available for all products and can be requested in the attributes[] parameter:
AttributeDescription
idUnique product identifier (always included)
titleProduct title
handleURL-friendly product handle
body_htmlProduct description HTML
vendorProduct vendor/brand
product_typeProduct type classification
tagsArray of product tags
imagesArray of product images
availableProduct availability status
created_atProduct creation timestamp
updated_atProduct last update timestamp
published_atProduct publication timestamp
price_rangeProduct price range object
optionsAvailable product options (filtered by availability)
original_optionsAll product options (unfiltered)
metafieldsProduct metafields object
named_tagsParsed key:value tags object
calculatedCalculated attributes object
categoryShopify Product Taxonomy category
featured_mediaFeatured product media
is_gift_cardGift card indicator
has_variants_that_require_componentsBundle product indicator
combined_listing_parent_product_idParent product ID for combined listings
combined_listing_roleRole in combined listing (PARENT/CHILD)

​
Special Attributes

AttributeDescription
first_or_matched_variantReturns the first available variant or the variant matching applied filters. Must be explicitly requested.

​
Example API Request

{
  "attributes": [
    "id",
    "title",
    "handle",
    "images",
    "price_range",
    "vendor",
    "first_or_matched_variant"
  ],
  "sort_order_code": "best-selling"
}

​
Example Response with Selected Attributes

{
  "results": [
    {
      "id": 7003338965178,
      "title": "Premium Cotton T-Shirt",
      "handle": "premium-cotton-t-shirt",
      "images": [
        {
          "alt": "Premium Cotton T-Shirt - Front",
          "src": "https://cdn.shopify.com/s/files/product-front.jpg",
          "width": 800,
          "height": 800,
          "variant_ids": []
        }
      ],
      "price_range": {
        "from": 29.99,
        "to": 34.99,
        "compare_at_price": 39.99
      },
      "vendor": "Brand Name",
      "first_or_matched_variant": {
        "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"}
        ]
      }
    }
  ],
  "totalResults": 150,
  "page": 1,
  "totalPages": 15
}
By default, if no attributes parameter is provided, all available attributes are included in the response. Specifying attributes helps reduce response payload size and improve performance.