Shopify Metafields: Complete Setup and Display Guide

A Shopify metafield is a custom key-value field you attach to a store resource (product, collection, order, customer, variant, and more) to store data that Shopify's core schema does not natively provide. You define the data type, enforce validation, and then surface the value anywhere: your storefront via Liquid, your analytics via ShopifyQL, your checkout via Shopify Functions, or your external systems via the GraphQL Admin API. That three-step loop (define, populate, display) is the entire mental model you need.

Key takeaways

• A metafield is identified by three things: owner resource, namespace, and key. Change any one of these and you are referencing a different field.
• Shopify's Spring '26 and Summer '26 Editions shipped several metafield upgrades: pin up to 50 fields on admin pages, cart metafields that carry over to orders, metafields on inventory transfers, and ShopifyQL dot-syntax filtering.
• The Admin GraphQL API 2026-07 release candidate lets you define and set metafields directly on inventory transfers without a separate metafieldsSet call.
• Creating a definition does not display anything on your storefront. You still need to connect the field via a dynamic source in the theme editor, or write the Liquid yourself.
• Standard definitions (care instructions, ingredients, size, ISBN, etc.) are the fastest path because they are pre-configured, theme-compatible, and app-interoperable out of the box.

What exactly is a Shopify metafield?

Metafields enable you to attach additional information to a Shopify resource, such as a product or a collection. The data can be specifications, size charts, downloadable documents, release dates, images, or part numbers. Every metafield stores a value alongside type information, and it is identified by its owner resource, namespace, and key.

Think of the namespace as a folder name and the key as the file name inside that folder. A product metafield with namespace: custom and key: material is completely separate from one with namespace: specs and key: material, even though both live on the same product.

The three ownership models

Understanding ownership stops you from accidentally overwriting data you did not mean to touch.

Merchant-owned metafields use any non-reserved namespace (such as custom, specs, or inventory). All installed apps can read and write them. They are ideal for shared data that multiple apps consume.

App-owned metafields use the reserved $app namespace prefix. The owning app controls the structure and values, which are view-only in the admin by default. Use these when one app is the authoritative source for a piece of data.

App-data metafields are tied to a specific app installation and are completely hidden from the Shopify admin. They live on the AppInstallation resource and can only be accessed by the owning app via GraphQL or through the app object in Liquid. These are for internal app state that should never surface to merchants.

Shopify also maintains Shopify-reserved namespaces (prefixed shopify--) for platform-managed fields such as standard definitions.

Metafield data types: a practical map

Shopify groups types into categories. Choosing the right type matters because it enforces validation, controls how Liquid renders the value, and determines which filters apply.

Text

• single_line_text_field, product badges, short labels, ISO codes
• multi_line_text_field, ingredient lists, care instructions (newlines preserved)
• rich_text, formatted long-form content (headings, bold, lists); render with the metafield_tag filter

Numbers and measurements

• number_integer, number_decimal
• dimension, volume, weight, each stores a numeric value paired with a unit; ideal for product specs and shipping rules

Dates and times

• date, date_time, launch dates, expiration dates, event schedules

References

• product_reference, collection_reference, page_reference, variant_reference, link one resource to another without duplicating data
• metaobject_reference, link to a metaobject entry (see below)
• article_reference and list.article_reference, added in the 2025-10 API release; let you tie products directly to blog posts for content-driven commerce and SEO

Other useful types

• boolean, feature flags, "new arrival" toggles, hide-from-sale markers
• color, hex-based color values with native swatch support
• url, file_reference, downloadable PDFs, spec sheets, videos
• json, arbitrary structured data; useful but harder to validate and render

For list types, prefix any scalar type with list. (for example, list.single_line_text_field). These render as arrays in Liquid and are the right choice whenever a field can hold multiple values, such as a list of materials or a set of pickup locations.

One important constraint: when using the GraphQL Admin API, the metafield value is always entered and stored as a string, regardless of the declared type. Shopify handles type coercion on read.

Metafield definitions: why they matter

You can write a raw metafield (no definition) through the API, but definitions are almost always the right choice. A metafield definition establishes a schema that all values for that namespace-key combination must follow, including the data type and validation constraints. The definition also controls access permissions across the GraphQL Admin API, Storefront API, and Customer Account API, and determines whether the field can be used for admin filtering or as a collection condition.

Building with definitions means:

• Admin UI support. Defined fields appear on every relevant resource's edit page without any custom code.
• Validation. Invalid values are caught before they corrupt your storefront.
• Filtering. You can use a defined field as a smart collection condition or as an admin filter.
• Theme editor discovery. Dynamic source pickers only surface defined fields.

Standard definitions are pre-built schemas for common use cases such as ISBN numbers, product ingredients, and care instructions. Using them means apps and themes that reference those standard namespaces will already know how to read your data without extra configuration.

Step-by-step: create a definition and populate it

In the Shopify admin (no code)

1. Go to Settings > Custom data.
2. Choose the resource type (Products, Customers, Orders, etc.).
3. Click Add definition. Name it, choose a content type, and save.
4. As of Shopify's Spring '26 Edition, you can also create metafields directly from customers, orders, and collection pages without navigating to Settings first.
5. Open any product (or other resource) and scroll to the Metafields section to fill in values.

Spring '26 also introduced the ability to pin up to 50 metafields on product, customer, and order sections so your team can see and edit the most important fields without clicking into a separate page.

Via the GraphQL Admin API

For bulk operations or automated pipelines, use metafieldDefinitionCreate (to create the schema) followed by metafieldsSet (to write values). The metafieldsSet mutation allows a maximum of 25 metafields per call, with a maximum total request payload size of 10 MB, and the operation is atomic: no changes persist if an error occurs.

A minimal definition mutation looks like this:

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
    }
    userErrors {
      field
      message
    }
  }
}

With variables:

{
  "definition": {
    "name": "Material",
    "namespace": "custom",
    "key": "material",
    "type": "list.single_line_text_field",
    "ownerType": "PRODUCT",
    "useAsCollectionCondition": true
  }
}

Setting useAsCollectionCondition: true means you can immediately use this field to power smart collection rules, no extra step required.

For bulk catalog updates, tools like Matrixify let you import metafield values from a CSV without writing any API code.

Displaying metafields on your storefront

This is where most merchants get stuck. Creating the definition does not make the field appear on your storefront. You need to connect it.

Option 1: Dynamic sources in the theme editor (no code)

If you are on an Online Store 2.0-compatible theme (Dawn, Horizon, or any JSON-template theme), open the theme editor, add or click a section or block that supports dynamic sources, and click the connect dynamic source icon. You can add up to 20 metafields to a single template this way.

Option 2: Liquid (full control)

The Liquid syntax is:

{{ product.metafields.namespace.key }}

For a rich text metafield, use the metafield_tag filter to render HTML formatting correctly:

{{ product.metafields.custom.care_instructions | metafield_tag }}

For an image file reference:

{{ product.metafields.custom.hero_image.value | image_url: width: 800 | image_tag }}

One gotcha: if your metafield key is size, first, or last, use square bracket notation instead of dot notation: product.metafields.namespace["size"]. These words are also built-in Liquid filters, and dot notation will apply the filter rather than fetch the metafield when the key is missing.

For the five highest-impact product page use cases (custom content tabs, product badges, spec tables, downloadable PDFs, and related product lists), each needs its own definition and a matching Liquid block in your theme's sections/main-product.liquid.

What changed in 2026: the updates that matter

Spring '26 (announced mid-2026):

• Cart metafields carry over to orders. Enable cartToOrderCopyable on an order metafield definition and any cart metafield value from checkout is automatically copied to the resulting order. This is a major unlock for post-purchase logic in Shopify Flow.
• Create metafields without leaving the resource page. You no longer need to navigate to Settings > Custom data to add a new definition; you can do it inline from any customer, order, or collection record.
• Pin up to 50 metafields on product, customer, and order admin pages.
• ShopifyQL dot-syntax filtering. Metafields are now supported as dimensions and filters in ShopifyQL with dot-syntax, available through the Analytics API and the online editor. This means you can segment your analytics reports by any custom field you have defined.
• Simpler GraphQL API. The Spring '26 edition shipped a simplified read/write interface for metafields and metaobjects, reducing boilerplate in app code.
• Shop User metafields are readable during checkout via Shopify Functions, letting you build buyer-specific checkout customizations against stored customer data.

Admin GraphQL API 2026-07 (release candidate as of July 2026):

• Metafields on inventory transfers. You can now define and set metafields directly on inventory transfers to store lot numbers, supplier codes, freight details, or ERP reference IDs without a separate metafieldsSet call.

Winter '26:

• Metafields and metaobjects render faster on storefronts, support richer query filtering, and allow higher entry limits than previous API versions.

October 2025 (API 2025-10):

• Added article_reference and list.article_reference types, enabling merchants to create formal product-to-article links for content-driven SEO and editorial commerce flows.

Metafields vs. metaobjects: when to use which

A metafield stores a single piece of data on an existing resource. A metaobject is a reusable, standalone content entry with its own schema, multiple fields, and its own admin UI. Use metafields when the data belongs to and only makes sense on a specific product (or order, or customer). Use metaobjects when the content is reusable across multiple products, such as a shared size guide, a brand story, or a supplier profile.

You connect the two with a metaobject_reference metafield: the field on the product points to the metaobject entry, and updating the entry updates every product referencing it automatically.

Metafields and the AI shopping layer

This is the angle most merchants are missing in 2026. Shopify's Summer '26 "Everywhere Edition" made the Universal Commerce Protocol (UCP) active by default on every store, letting AI shopping agents read your catalog. The structured data inside your metafields (specs, ingredients, certifications, materials) is exactly what AI agents and Google's rich-result parsers consume when deciding whether to surface your product.

Category metafields deserve special attention here. These are product attributes that map to a specific product category and help make products more discoverable on your site, on marketplaces, and on search engines. When you assign the right product category in Shopify, you get default category metafield entries pre-populated (for example, a Shirts category gives you size, neckline, sleeve length, fabric, gender, and color fields). Fill them in consistently and you are feeding structured data to every downstream channel simultaneously.

If you have broken product descriptions into separate metafields for readability, note that you currently cannot map more than one Shopify field to a single Shopify Catalog description field. The workaround is to create a combined metafield that concatenates your description and key metafield data, then map that single field to the catalog.

Governance: the part most teams skip

Metafields are easy to create and very easy to let sprawl. A few rules that prevent expensive cleanup later:

• Document your schema. Maintain a reference sheet (a simple spreadsheet works) that records every namespace, key, type, owner resource, and which app or team owns the definition.
• Use standard definitions whenever one exists. They are interoperable, auto-validated, and immune to naming collisions.
• Never change a type after you have live data. Migrating from date_time to money, for example, makes all existing values invalid. Plan types correctly upfront.
• Namespace discipline. Use distinct namespaces per app or team (logistics, marketing, compliance) so you can audit and clean up by namespace without affecting unrelated fields.
• Test writes as atomic operations. The metafieldsSet mutation is atomic: either all 25 values in a single call succeed, or none do. Structure your bulk imports around this guarantee.

If you need help architecting a metafield schema for a complex catalog or integrating metafields into a custom storefront, see the Shopify developer services page or the Shopify theme developer work I do with merchants.

Quick reference: Liquid syntax cheat sheet

Metafields are one of those features where spending two hours learning the fundamentals saves you weeks of workarounds later. Define your schema carefully, use standard definitions wherever they exist, and connect your fields to both your storefront and your analytics layer. The 2026 updates, especially cart-to-order copying and ShopifyQL filtering, mean your metafield data is more actionable than ever.