Product Schema

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 Name	Type	Description	Example Value
id	Integer	Unique identifier for the product	`7003338965178`
title	String	Title of the product	`"SUPREME SEALLINE SEE POUCH SMALL"`
body_html	String	HTML content describing the product	`"The Supreme Sealline See Pouch Small is a versatile and..."`
vendor	String	The product’s vendor	`"SUPREME"`
product_type	String	Type of the product	`"Accessories"`
created_at	DateTime	DateTime when the product was created	`1644047925`
handle	String	A unique human-friendly string for the product, used in the product’s URL	`"supreme-pouch-44370ss18a32-sm"`
category	Object	The 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_id	Integer	`7003338965178`
combined_listing_role	String	`PARENT`
featured_media	Object	The 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_at	DateTime	DateTime when the product was last updated	`1698280024`
published_at	DateTime	DateTime when the product was published	`1644047925`
tags	Array of Strings	Tags associated with the product	`["Collection: Best Seller", "Collection:Accessories", "Collection:Supreme Accessories"]`
images	Array of Objects	Images related to the product.	`[{"alt": "SUPREME POUCH", "src": "https://cdn.shopify.com/", "width": 800, "height": 534, "variant_ids": []}]`
metafields	Object	Configured metafields for the product	`{"product": {"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK", "styleCode": "SS18A30 BLACK", "yearOfRelease": 2018}}`
available	Boolean	Availability status of the product	true
is_gift_card	Boolean	Whether the product is a gift card	false
has_variants_that_require_components	Boolean	Whether the product has variants that require bundle components (used for bundle products)	false
price_range	Object	Price range of the product, including from and to fields	`{"from": 7.97, "to": 7.97, "compare_at_price": 7.97}`
options	Object	Dynamically 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_options	Object	Dynamically 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"]}`
options_v2	Array of Objects	Enhanced options array with swatch and linked metafield data. Preserves Shopify’s option ordering and includes visual swatch information (color, image) and linked metafield values for each option value.	See options_v2 Structure below
named_tags	Object	Dynamically created object of ‘key:value’ tags on the product. Keys/values in this object are not included in the `tags` array	`{"YearOfRelease": 2016}`
calculated	Object	Calculated 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.

API Response Type Consistency

The following fields are guaranteed to always be returned as JSON objects (or null) in API responses, never as empty arrays. This ensures type consistency for API consumers and prevents type mismatches in strongly-typed clients:

metafields - Always an object or null
calculated - Always an object or null
named_tags - Always an object or null
category - Always an object or null
featured_media - Always an object or null
first_or_matched_variant - Always an object or null
price_range - Always an object or null

When these fields have no data, they will be returned as {} (empty object) or null, never as [] (empty array). This behavior is enforced at the API response level to maintain consistent typing across all endpoints.

Sequential array fields like tags and images are not affected by this enforcement and will continue to be returned as arrays.

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

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.

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 respects out-of-stock variant filtering based on your store settings. 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"
}

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:

Type	Description	Example
single_line_text_field	A single line of text used for titles, names, or other short descriptions.	`"Limited Edition"`
multi_line_text_field	Multiple lines of text, typically used for long descriptions or instructions.	`"Care instructions: Machine wash cold, tumble dry low."`
boolean	True or false value indicating binary states such as availability or inclusion.	`true`
number_integer	Whole numbers used for inventory counts, order limits, or other quantities.	`150`
number_decimal	Numbers with decimal places, often used for prices, weights, or measurements.	`29.99`
json	JSON objects used to store structured data such as configurations, specifications, or dynamic content.	`{"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK"}`
date	Date values formatted as YYYY-MM-DD, often used for production dates, release dates, or promotional periods.	`"2023-09-30"`
date_time	DateTime values formatted as ISO 8601, used for time-based events like product launches or sales end times.	`"2024-01-01T00:00:00.000Z"`
color	Color values formatted as hexadecimal strings, used for product colors or UI elements.	`"#FF5733"`
file_reference	Links 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_reference	Links to other product IDs, allowing cross-referencing of related items.	`"gid://shopify/Product/123456789"`
variant_reference	References to specific product variants, allowing differentiation between product options like size or color.	`"gid://shopify/ProductVariant/987654321"`
collection_reference	References to collections, used for categorization and dynamic grouping of products.	`"gid://shopify/Collection/456789123"`
page_reference	Links to Shopify pages, typically used for additional information or storytelling about a product.	`"gid://shopify/Page/654321987"`
metaobject_reference	References to custom metaobjects that can extend product data with additional attributes or structured information.	`"gid://shopify/Metaobject/321654987"`
url	URLs 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

Layers fully supports Shopify metaobjects, allowing you to leverage custom data structures defined in your Shopify admin. When a product metafield references a metaobject, Layers automatically hydrates the complete metaobject data during synchronization, giving you access to all fields defined on the metaobject.

Supported Reference Types

The schema supports the following reference types with full data hydration:

Reference Type	Description
`metaobject_reference`	Single reference to a custom metaobject
`list.metaobject_reference`	List of references to custom metaobjects
`product_reference`	Single reference to another product
`list.product_reference`	List of references to other products
`variant_reference`	Single reference to a product variant
`collection_reference`	Single reference to a collection
`page_reference`	Single reference to a Shopify page

Metaobject Data Structure

When metaobject references are hydrated, the data includes the metaobject’s ID, type, handle, display name, and all defined fields. Nested metaobject references within fields are also supported.

Example: Metaobject Reference Response

{
  "metafields": {
    "custom": {
      "color_swatch": {
        "id": "gid://shopify/Metaobject/123456",
        "type": "color_swatch",
        "handle": "midnight-blue",
        "displayName": "Midnight Blue",
        "fields": [
          { "key": "color", "type": "color", "value": "#191970" },
          { "key": "name", "type": "single_line_text_field", "value": "Midnight Blue" },
          { "key": "hex_code", "type": "single_line_text_field", "value": "#191970" }
        ]
      }
    }
  }
}

Example: List Metaobject Reference Response

{
  "metafields": {
    "custom": {
      "available_colors": [
        {
          "id": "gid://shopify/Metaobject/111",
          "type": "color_swatch",
          "handle": "red-swatch",
          "displayName": "Red",
          "fields": [
            { "key": "color", "type": "color", "value": "#FF0000" }
          ]
        },
        {
          "id": "gid://shopify/Metaobject/222",
          "type": "color_swatch",
          "handle": "blue-swatch",
          "displayName": "Blue",
          "fields": [
            { "key": "color", "type": "color", "value": "#0000FF" }
          ]
        }
      ]
    }
  }
}

Metaobject data is automatically hydrated during catalog synchronization. If reference data is unavailable, Layers falls back to storing the numeric ID of the referenced object.

For a complete list of supported metafield 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 Path	Attribute Code
`metafields.custom.material`	`metafields.custom.material`
`metafields.product.colorway`	`metafields.product.colorway`
`metafields.seo.meta_title`	`metafields.seo.meta_title`

Accessing Nested Metafield Object Keys

When a metafield value is a JSON object, you can create attributes that access nested object keys using dot notation. The namespace and key portions must follow standard naming conventions (alphanumeric and underscores), but object keys can contain spaces and special characters. Format: metafields.{namespace}.{key}.{object_key} Example metafield value:

{
  "metafields": {
    "algolia": {
      "color_family": {
        "dark orange": "orange",
        "light blue": "blue",
        "forest green": "green"
      }
    }
  }
}

Attribute codes for nested object keys:

Object Key	Attribute Code
`dark orange`	`metafields.algolia.color_family.dark orange`
`light blue`	`metafields.algolia.color_family.light blue`
`forest green`	`metafields.algolia.color_family.forest green`

Use cases:

Filtering: Create filterable attributes for nested metafield values to enable faceted navigation (e.g., filter by color family values)
Faceting: Display facet counts for nested object values in browse and search results
Sorting: Sort products by nested metafield object values
Merchandising: Use nested metafield values in collection rules and merchandising logic

This feature supports both metafields and variant_metafields with the same syntax. Variant metafield example: variant_metafields.custom.size_details.extra large

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.

Only attributes marked as visible on storefront can be requested in the attributes parameter or used in filters. Attributes marked as not visible (such as internal calculated fields) will be rejected if included in API requests. See Visible on Storefront for more details.

Core Product Attributes

The following attributes are available for all products and can be requested in the attributes[] parameter:

Attribute	Description
`id`	Unique product identifier (always included)
`title`	Product title
`handle`	URL-friendly product handle
`body_html`	Product description HTML
`vendor`	Product vendor/brand
`product_type`	Product type classification
`tags`	Array of product tags
`images`	Array of product images
`available`	Product availability status
`created_at`	Product creation timestamp
`updated_at`	Product last update timestamp
`published_at`	Product publication timestamp
`price_range`	Product price range object
`options`	Available product options (filtered by availability)
`original_options`	All product options (unfiltered)
`options_v2`	Enhanced options array with swatch and linked metafield data
`metafields`	Product metafields object
`named_tags`	Parsed key:value tags object
`calculated`	Calculated attributes object
`category`	Shopify Product Taxonomy category
`featured_media`	Featured product media
`is_gift_card`	Gift card indicator
`has_variants_that_require_components`	Bundle product indicator
`combined_listing_parent_product_id`	Parent product ID for combined listings
`combined_listing_role`	Role in combined listing (PARENT/CHILD)

Special Attributes

Attribute	Description
`first_or_matched_variant`	Returns 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.

Overview

Core Features

Engine

LayersQL

Shopify Integration

Misc

Legal

​Product Schema Overview

​Schema Fields

​API Response Type Consistency

​Variant Data with first_or_matched_variant

​When to Use first_or_matched_variant

​Variant Schema Fields

​Example first_or_matched_variant Response

​options_v2 Structure

​options_v2 Schema Fields

​Option Value Schema Fields

​Swatch Object Schema

​Example options_v2 Response

​Example Product (JSON)

​Data Types and Formatting

​Supported Metafield Types

​Special Metafields for Layers Features

​Automatic Sequence Creation

​Metaobject & Reference Handling

​Supported Reference Types

​Metaobject Data Structure

​Example: Metaobject Reference Response

​Example: List Metaobject Reference Response

​Metafield Structure and Examples

​Metafield Structure

​Example: Custom Product Metafields

​Accessing Metafields in Attributes

​Accessing Nested Metafield Object Keys

​Example: List-Type Metafields

​Available Attributes for API Requests

​Core Product Attributes

​Special Attributes

​Example API Request

​Example Response with Selected Attributes

Product Schema Overview

Schema Fields

API Response Type Consistency

Variant Data with first_or_matched_variant

When to Use first_or_matched_variant

Variant Schema Fields

Example first_or_matched_variant Response

options_v2 Structure

options_v2 Schema Fields

Option Value Schema Fields

Swatch Object Schema

Example options_v2 Response

Example Product (JSON)

Data Types and Formatting

Supported Metafield Types

Special Metafields for Layers Features

Automatic Sequence Creation

Metaobject & Reference Handling

Supported Reference Types

Metaobject Data Structure

Example: Metaobject Reference Response

Example: List Metaobject Reference Response

Metafield Structure and Examples

Metafield Structure

Example: Custom Product Metafields

Accessing Metafields in Attributes

Accessing Nested Metafield Object Keys

Example: List-Type Metafields

Available Attributes for API Requests

Core Product Attributes

Special Attributes

Example API Request

Example Response with Selected Attributes