Shopify Metafields Explained, with Examples

Who it is for

Stores with product details beyond the basics

Time needed

An hour to set up the first field

What you need

Admin access and a 2.0 theme

A candle brand wants burn time on every product page. A clothing store wants fabric and care details under the price. A parts supplier wants voltage and dimensions in a spec table and as filters. Shopify's product form has a title, a description, price and variants, and nowhere sensible for any of this.

That's what metafields are for. Stuffing the details into the description works until you want to style them, filter by them or change them on 300 products. This guide explains Shopify metafields with real examples, from creating the definition to showing it in your theme, with and without code. Steps and limits come from Shopify's help center and shopify.dev as I checked them on 7 November 2026.

Shopify metafields explained

A metafield is an extra field attached to something in your store. Shopify supports them on products, variants, collections, customers and orders, among others. Each one has two parts:

• A definition, created once: the name, the type of data (text, number, file, product and so on), any validation rules, and a namespace and key. For a field called "Care guide", Shopify generates custom.care_guide, where custom is the namespace and care_guide the key. Each namespace and key pair must be unique.
• Values, entered per product, variant or customer, in the Metafields section of that item's page in the admin.

Shopify also provides standard definitions for common fields, and category metafields linked to a product's category, which come with default entries.

Metafields vs metaobjects

A metafield holds one piece of data on one item. A metaobject is a reusable object with several fields of its own, such as a designer with a name, photo and bio, or an ingredient with an icon, title and description. You define metaobjects under Settings (labeled Custom data or Metafields and metaobjects, depending on your admin) and add entries under Content > Metaobjects.

The two work together. A product metafield of type metaobject reference can point to a designer entry, so you write the designer's bio once and link it from 40 products. If the same block of information repeats across many products, it should be a metaobject. If it's unique to each product, a plain metafield is enough.

Choose the right metafield type

The type decides what can be entered and how the theme can use it. Choose carefully, because the type controls validation, filtering and how the theme can display the value. These are the types I use most:

Most types also come as a list, such as list.single_line_text_field or list.product_reference, by choosing List of values when you create the definition. Rich text, multi-line text, true or false, money and JSON have no list version.

Step 1: Create a metafield definition

1. Open the definitions. Go to Settings > Metafields and metaobjects and pick the resource, such as Products. You can also start from any product page: scroll to the Metafields section and click Add definition.
2. Name it. Enter a clear name, such as "Care guide". If Shopify suggests a standard definition that matches, click it instead.
3. Check the namespace and key. Shopify generates them from the name. Edit them now if needed. Your theme code will refer to them, so keep them short and stable.
4. Select a type. Click Select type and choose, for example, Rich text or File > Image. Switch One value to List of values if you need several.
5. Add validation. If a Validation section appears, set rules such as minimum and maximum values or character limits.
6. Set access. Tick Storefronts if a headless or custom storefront needs the data. For product and variant metafields, tick Smart collections if you want to use the field in automated collection conditions.
7. Save. The definition is pinned by default, so it shows on every product page in the admin.

Step 2: Add values to your products

Open a product and fill in the new field in its Metafields section, then save. For many products at once, use the bulk editor:

1. Select products. On the Products page, tick the products to edit.
2. Open the editor. Click Edit products, then Columns.
3. Add the metafield columns. In the Metafields section, choose the fields to edit.
4. Fill in and save. Enter values in the table and click Save. Fix any validation errors and save again.

Shopify notes that bulk editing product metafields in Microsoft Edge can cause errors because of URL length limits, so use Chrome, Firefox or Safari for this job.

Step 3: Show metafields in your theme without code

Online Store 2.0 themes, including Dawn and the other free Shopify themes, support dynamic sources: a section or block setting can take its value from a metafield instead of fixed text.

1. Open your product template. In the theme editor, switch the template menu to Products > Default product.
2. Add a block. In the Product information section, add a Text block or a Collapsible row, for example.
3. Connect the source. Click the dynamic source icon next to the setting, search for your metafield and select it.
4. Save and check. Open a product with a value and one without, and check that the block looks right on both.

You can connect up to 20 metafields to a single template this way. Product reference lists are the main exception: they need a theme or custom section with a product list setting.

Step 4: Use metafields in Liquid

For layouts the editor can't produce, a developer reads metafields in Liquid. The pattern is resource.metafields.namespace.key, and .value returns the data. If you're new to Liquid, my Liquid basics guide covers the syntax.

A number with a unit:

{%- assign burn = product.metafields.custom.burn_time.value -%}
{%- if burn -%}
  <p>Burn time: {{ burn }} hours</p>
{%- endif -%}

A true or false badge:

{%- if product.metafields.custom.vegan.value -%}
  <span class="badge">Vegan</span>
{%- endif -%}

A list of "pairs with" products. For reference types, .value returns the real product objects, so you can use their titles, URLs and images:

{%- assign pairs = product.metafields.custom.pairs_with.value -%}
{%- if pairs.count > 0 -%}
  <ul>
  {%- for item in pairs -%}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
  {%- endfor -%}
  </ul>
{%- endif -%}

Rich text and other types render well with the metafield_tag filter, which outputs HTML suited to the type: {{ product.metafields.custom.care_guide | metafield_tag }}. It supports most single-value types, but among lists only list.single_line_text_field and list.metaobject_reference.

One gotcha: if your key is size, first or last, use square brackets, as in product.metafields.custom["size"], because dot notation can return a built-in property instead.

Use metafields as collection filters

Metafields can also power filters on collection and search pages through the free Shopify Search & Discovery app. Filtering supports single line text, lists of single line text, metaobject references, integers, decimals and true or false metafields. Text fields work best when values are consistent: "Cotton" and "cotton " become two separate filter values. The setup is in my guide to setting up product filters in Shopify.

Do you need a Shopify metafields app?

For most stores, no. Creating definitions, entering values, bulk editing, connecting them to the theme and filtering are all built into Shopify now. Apps still help with large imports and exports, copying values between stores, or editing types the bulk editor handles awkwardly. Before you install one, check whether the native bulk editor already does the job.

Common metafield mistakes

• Using text for everything. A number stored as text can't be validated or filtered as a range. Pick the real type.
• Renaming keys later. Theme code and connected sources refer to the namespace and key. Changing them breaks the link.
• Duplicating repeated content. If 50 products share one block of text, use a metaobject or a page instead.
• Printing empty wrappers. Check for a value before outputting HTML around it.
• Forgetting Storefronts access on a headless store, which hides the data from the custom storefront.
• Inconsistent values in fields you plan to filter on.

Metafields checklist

• List the product details that don't fit standard fields.
• Decide for each: plain metafield, list, or metaobject.
• Create definitions with the right type, short keys and validation.
• Fill values with the bulk editor, using consistent wording.
• Connect fields to theme blocks with dynamic sources, and check products with and without values.
• Set up filters for the fields shoppers choose by.
• Document your namespaces and keys for whoever edits the theme next.

Next steps

Start with one field that would help shoppers decide, such as dimensions or materials, and set it up end to end before adding more. If you're also tidying your catalog, my guide to adding products the right way pairs well with this one. If you need a custom section or spec table built around your metafields, that's part of my Shopify development service, which starts from $300 with a fixed quote.

Frequently asked questions

Sources

1. Metafields, Shopify Help Center
2. Creating custom metafield definitions, Shopify Help Center
3. Displaying metafields on your online store, Shopify Help Center
4. List of metafield data types, Shopify.dev
5. metafield object, Shopify.dev
6. metafield_tag filter, Shopify.dev

Related services and work

Written by Ashraf Siddik

I'm a Shopify developer and CRO specialist. I have built and improved Shopify stores since 2018, completed more than 1,000 projects, and hold a 4.96 average rating across 719 client reviews.

About me · Client reviews