Metafields

Metafields extend products with custom structured data. Layers supports the standard Shopify metafield types and provides predictable access patterns for using metafield values as searchable, filterable, and sortable attributes. This page covers the core metafield contract. See these related pages for deeper topics:

Metaobjects and reference metafields - metaobject resolution, nested references, and normalized reference shapes.
Automatic sequences from metafields - turn list.product_reference metafields into product sequences.
Available attributes for API requests - the full list of attributes you can request from the Search, Browse, and Blocks APIs.

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. For a complete list of supported metafield types and their properties, 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

Structured metafield subfield leaves

Shopify’s structured metafield types (money, weight, volume, dimension, and rating, plus their list.* variants) decode into JSON objects, not scalars. The parent attribute code is not directly filterable or sortable. You address the scalar leaves inside the object instead. Layers indexes numeric leaves with numeric semantics, so filters and sort orders compare 19.90 < 100.00 correctly. Without this, string ordering would put "100.00" before "19.90". The available leaves per type:

Metafield type	Numeric leaves	String leaves
`money`	`amount`	`currency_code`
`weight`	`value`	`unit`
`volume`	`value`	`unit`
`dimension`	`value`	`unit`
`rating`	`value`, `scale_min`, `scale_max`	—

Example: a custom.price money metafield exposes these attribute codes:

metafields.custom.price.amount: numeric. Use for range filters and sort orders.
metafields.custom.price.currency_code: string. Use as a facet.

Filter by amount on a Search or Browse request:

{
  "property": "metafields.custom.price.amount",
  "operator": "gte",
  "values": [19.9]
}

Sort by amount ascending:

{
  "property": "metafields.custom.price.amount",
  "direction": "asc"
}

Attribute paths for reference metafields

When a metafield is a reference type (such as metaobject_reference, file_reference, or taxonomy), Layers discovers curated nested attribute paths instead of the base metafield code. This gives you access to the specific values within the normalized reference structure that are useful for filtering, sorting, and display. See Metaobjects and reference metafields for the full normalized shapes and every supported attribute path. Metaobject reference attributes: For metaobject references, the available attribute paths target the base reference (the metaobject handle), the display name, and individual fields:

Attribute Path	Description
`metafields.{namespace}.{key}`	The referenced metaobject’s handle. Available for `metaobject_reference` and `list.metaobject_reference` definitions where every reference targets a single metaobject definition type. Use this as a facet or filter value to group products by which metaobject they reference. `mixed_reference` is not supported because handles are only unique within one definition type.
`metafields.{namespace}.{key}.display_name`	The display name of the metaobject
`metafields.{namespace}.{key}.fields.{field_key}`	A specific field value within the metaobject

Example: If you have a custom.specification metaobject reference with fields material and finish, Layers discovers these attribute codes:

metafields.custom.specification (the handle of the referenced specification metaobject)
metafields.custom.specification.display_name
metafields.custom.specification.fields.material
metafields.custom.specification.fields.finish

When you use the base metaobject-reference path (metafields.{namespace}.{key}) as a facet, filter UIs receive raw handles. Set enrichFacetMetaobjects to true on your facet, search, or browse request to also receive a facetDisplay map with each handle’s display_name and fields for labels and swatch data.

Media and file reference attributes: For image and file references, the available paths are:

Attribute Path	Description
`metafields.{namespace}.{key}.url`	The CDN URL of the referenced file
`metafields.{namespace}.{key}.alt`	The alt text of the referenced image

Taxonomy reference attributes: For taxonomy value references, the available path is:

Attribute Path	Description
`metafields.{namespace}.{key}.name`	The display name of the taxonomy value

For file_reference and taxonomy metafields, the base metafield code (for example, metafields.custom.hero_image) is not available as an attribute. Use one of the nested paths listed above instead. For metaobject references, the base code is available as a single-value handle attribute only when every reference targets one metaobject definition type. mixed_reference remains unavailable. Transport-only paths such as __typename, .type, and .handle on nested references are always excluded from attribute creation.

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

Overview

Metafields

Supported metafield types

Metafield structure and examples

Metafield structure

Example: custom product metafields

Accessing metafields in attributes

Accessing nested metafield object keys

Structured metafield subfield leaves

Attribute paths for reference metafields

Example: list-type metafields

See also

​Supported metafield types

​Metafield structure and examples

​Metafield structure

​Example: custom product metafields

​Accessing metafields in attributes

​Accessing nested metafield object keys

​Structured metafield subfield leaves

​Attribute paths for reference metafields

​Example: list-type metafields

​See also

Supported metafield types

Metafield structure and examples

Metafield structure

Example: custom product metafields

Accessing metafields in attributes

Accessing nested metafield object keys

Structured metafield subfield leaves

Attribute paths for reference metafields

Example: list-type metafields

See also