Metafields & References

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 configurable metafields. You can configure which metafields trigger automatic sequence creation through the dashboard at Configuration > Product Sequences (/configure/product-sequences).

Configuration options

Each sequence metafield configuration requires:

Namespace: The metafield namespace (e.g., layers, custom)
Key: The metafield key (e.g., global_sequence, related_products)
Type: Must be list.product_reference in Shopify
Includes current product: Whether the metafield value already contains the current product

Default configuration

By default, Layers recognizes the layers.global_sequence metafield:

Namespace: layers
Key: global_sequence
Type: list.product_reference
Includes current product: Yes

When this metafield is present on products, Layers will automatically create a global sequence named “Auto: layers.global_sequence” during bulk data synchronization. The metafield value should contain an array of product references that should be grouped together in the sequence. During automatic sequence creation and updates, Layers resolves global sequence conflicts automatically. If a product already belongs to another global sequence, it is removed from the old group before being placed in the new one. If removing products causes an old group to contain one or fewer products, that group is deleted.

Custom configurations

You can add additional metafield configurations for different use cases. For example, a “related products” metafield:

Namespace: custom
Key: related_products
Type: list.product_reference
Includes current product: No

When “includes current product” is disabled, Layers will automatically prepend the current product to the metafield value when creating the sequence. This is useful when the metafield contains only related products, not the product itself. Each configured metafield will create sequences named as Auto: {namespace}.{key} (e.g., “Auto: custom.related_products”).

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 resolves the complete metaobject data from a local cache, giving you access to all fields defined on the metaobject — including nested metaobject references up to 5 levels deep.

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 resolved, the data includes the metaobject’s ID, type, handle, display name, and all defined fields as key-value pairs. If a field within a metaobject itself references another metaobject, that reference is also resolved recursively.

Field	Type	Description
`id`	String	The Shopify GID of the metaobject
`type`	String	The metaobject definition type
`handle`	String	The metaobject handle
`display_name`	String or null	The display name of the metaobject
`fields`	Object	Key-value map of resolved field data

Nested metaobject resolution

When a metaobject field references another metaobject (via metaobject_reference or list.metaobject_reference), Layers automatically resolves the nested reference from its local cache. This happens recursively up to 5 levels deep, with circular reference protection to prevent infinite loops. This is useful for data models where metaobjects reference other metaobjects — for example, a “Product Spec” metaobject that references a “Material” metaobject, which in turn references a “Certification” metaobject. Non-reference fields are returned as their plain values (strings, numbers, etc.). If a referenced metaobject is not found in the cache, the raw Shopify GID is returned as a fallback.

Example: metaobject reference response

{
  "metafields": {
    "custom": {
      "color_swatch": {
        "id": "gid://shopify/Metaobject/123456",
        "type": "color_swatch",
        "handle": "midnight-blue",
        "display_name": "Midnight Blue",
        "fields": {
          "color": "#191970",
          "name": "Midnight Blue",
          "hex_code": "#191970"
        }
      }
    }
  }
}

Example: list metaobject reference response

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

Example: nested metaobject reference response

In this example, a product has a “material” metafield that references a Material metaobject, which itself has a “certification” field referencing a Certification metaobject:

{
  "metafields": {
    "custom": {
      "material": {
        "id": "gid://shopify/Metaobject/500",
        "type": "material",
        "handle": "organic-cotton",
        "display_name": "Organic Cotton",
        "fields": {
          "name": "Organic Cotton",
          "weight": "150gsm",
          "certification": {
            "id": "gid://shopify/Metaobject/600",
            "type": "certification",
            "handle": "gots-certified",
            "display_name": "GOTS Certified",
            "fields": {
              "name": "Global Organic Textile Standard",
              "level": "Grade A",
              "url": "https://example.com/gots"
            }
          }
        }
      }
    }
  }
}

Metaobject data is resolved from a local cache that is kept in sync with Shopify via webhooks. If a referenced metaobject is not found in the cache, Layers falls back to the original reference data from Shopify’s GraphQL response, or the numeric ID if no reference data is available.

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": {
    "custom": {
      "color_family": {
        "dark orange": "orange",
        "light blue": "blue",
        "forest green": "green"
      }
    }
  }
}

Attribute codes for nested object keys:

Object Key	Attribute Code
`dark orange`	`metafields.custom.color_family.dark orange`
`light blue`	`metafields.custom.color_family.light blue`
`forest green`	`metafields.custom.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.
`variants`	Returns an array of all product variants ordered by position. Each variant has the same fields as `first_or_matched_variant`. 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 Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Metafields & References

Supported metafield types

Special metafields for Layers features

Automatic sequence creation

Configuration options

Default configuration

Custom configurations

Metaobject & reference handling

Supported reference types

Metaobject data structure

Nested metaobject resolution

Example: metaobject reference response

Example: list metaobject reference response

Example: nested 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

See also

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

​Supported metafield types

​Special metafields for Layers features

​Automatic sequence creation

​Configuration options

​Default configuration

​Custom configurations

​Metaobject & reference handling

​Supported reference types

​Metaobject data structure

​Nested metaobject resolution

​Example: metaobject reference response

​Example: list metaobject reference response

​Example: nested 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

​See also

Supported metafield types

Special metafields for Layers features

Automatic sequence creation

Configuration options

Default configuration

Custom configurations

Metaobject & reference handling

Supported reference types

Metaobject data structure

Nested metaobject resolution

Example: metaobject reference response

Example: list metaobject reference response

Example: nested 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

See also