How to Use Shopify Metafields for Products: Complete Guide (2026)

Store Custom Product Data Without Writing Code

Every Shopify product comes with a title, description, price, and images out of the box — but what happens when you need to display a burn time for candles, a fabric composition for clothing, or a compatibility chart for tech accessories? That is exactly where you learn how to use Shopify metafields for products to store and surface custom data that the default product fields simply cannot handle.

Metafields have been part of Shopify for years, yet the 2023 rollout of Online Store 2.0 and the continued improvements through 2025 and 2026 have turned them from a developer-only feature into a merchant-friendly powerhouse. You no longer need to write code or install third-party apps just to attach an extra text field to a product. The Shopify admin now provides a visual interface for creating metafield definitions, entering values, and connecting those values to your theme — all without touching a single line of Liquid.

In this guide, you will walk through everything from foundational concepts to production-ready Liquid snippets. Whether you are a store owner adding your first custom field or a Shopify developer building reusable theme sections, this article gives you a clear, step-by-step path to mastering product metafields.

---

What Are Shopify Metafields?

Metafields are custom data fields that extend the information Shopify stores about products, collections, customers, orders, and other resources. Think of them as extra columns you bolt onto an existing database table.

Why Products Need Extra Fields

The standard product editor covers the basics — title, description, vendor, product type, tags, and variants. But real-world catalogs demand more:

• Specifications — weight tolerance, voltage, thread count
• Compliance data — certifications, country of origin, allergen warnings
• Marketing details — badge text ("New Arrival"), promotional countdown dates
• Rich media — size chart PDFs, assembly videos, 360-degree spin images

Without metafields, merchants resort to stuffing this data into the product description HTML or relying on tags, both of which are fragile and hard to style.

How Metafields Are Structured

Every metafield has three core components:

You reference a product metafield in Liquid using the pattern product.metafields.namespace.key. For example, product.metafields.custom.care_instructions retrieves the care instructions value you entered in the admin.

The namespace-and-key system means you can have dozens of metafields on a single product without naming collisions, as long as each namespace-key pair is unique.

---

Standard vs. Custom Metafield Definitions

Before you start creating metafields, you need to understand the two categories of definitions that Shopify supports. Choosing the right one saves you time and ensures compatibility across themes and apps.

Standard Definitions

Shopify provides a library of pre-built metafield definitions for common use cases. These are maintained by Shopify and are designed to work seamlessly with themes, apps, and the broader platform ecosystem.

Examples of standard definitions include:

• Care guide — product washing and handling instructions
• Ingredients / Materials — what the product is made of
• Product subtitle — supplementary headline text
• ISBN — International Standard Book Number for published works
• Rating — star rating with scale and count

Standard definitions come with a fixed namespace (shopify or the resource-specific namespace), a predetermined key, and a validated content type. You should always prefer a standard definition when one exists for your use case, because it guarantees theme and app interoperability.

Custom Definitions

When no standard definition matches your needs, you create a custom definition. This is where you define your own namespace, key, display name, description, and content type.

Custom definitions are unique to your store. They work perfectly within your theme, but third-party apps will not automatically recognize them unless those apps explicitly read your custom namespace and key.

When to Use Each

The rule of thumb: check the Shopify standard definitions list first. Only create a custom definition if nothing matches.

---

Metafield Data Types Explained

Shopify enforces typed metafields, meaning you must declare what kind of data each metafield will hold. This validation prevents bad data from entering your store and enables Shopify to render the correct input widget in the admin.

Common Data Types

Here is a breakdown of the data types you will use most often for product metafields:

List Types

Most data types support a list variant, which stores multiple values in a single metafield as a JSON array. For example, list.single_line_text_field lets you store several text strings — useful for features like a bullet-point list of product highlights or multiple certification labels.

You enable the list variant by toggling "List of values" when creating the definition in the admin.

Choosing the Right Type

Pick the most specific type available. Use rating instead of number_decimal for star ratings. Use color instead of single_line_text_field for hex codes. The more specific the type, the better the admin editing experience and the more formatting options your theme gets. For a complete reference, see the official data types documentation.

---

How to Create Product Metafield Definitions

Now that you understand the concepts, let's walk through the actual setup process in your Shopify admin.

Step-by-Step: Admin Setup

1. Navigate to Settings — In your Shopify admin, go to Settings > Custom data (sometimes labeled Settings > Metafields and metaobjects depending on your plan).
2. Select Products — Click on Products from the list of resource types.
3. Add Definition — Click the Add definition button in the top right.
4. Choose Standard or Custom — Shopify will show you available standard definitions first. If one matches, select it and you are done. Otherwise, click Add custom definition.
5. Fill in the Definition Fields:

• Name — A human-readable label (e.g., "Burn Time")
• Namespace and key — Auto-generated from the name, or set manually (e.g., custom.burn_time)
• Description — Optional but recommended; tells other admins what this field is for
• Type — Select from the data type list (e.g., number_integer)
• Validation — Optional rules like minimum/maximum values or required character counts

1. Save — Click Save to create the definition.

Adding Values to Products

Once the definition exists, you enter values on individual products:

1. Go to Products in your admin and open any product.
2. Scroll down to the Metafields section at the bottom of the product editor.
3. Find your new metafield definition and enter the value.
4. Click Save.

You can also enter metafield values in bulk using CSV imports or tools like Matrixify, which is especially useful for stores with hundreds or thousands of products.

Using Preset Choices

For metafields where the value should come from a controlled list — like a "Material" field with options such as Cotton, Polyester, and Silk — enable Limit to preset choices in the definition. This gives merchants a dropdown instead of a free-text input, which eliminates typos and ensures consistency across your product catalog.

---

Displaying Metafields with Dynamic Sources (No Code)

One of the most powerful features of Online Store 2.0 themes is the ability to connect metafields to theme sections and blocks without writing any code. Shopify calls this feature dynamic sources.

How Dynamic Sources Work

When you edit a section in the theme customizer, any text, image, or URL setting can pull its value from a metafield instead of a manually entered value. This means:

• A text block can display product.metafields.custom.care_instructions
• An image block can render a file_reference metafield
• A URL field can link to a product_reference metafield

The connection is made through the small database icon next to each setting field in the theme editor.

Step-by-Step: Connecting a Metafield in the Theme Editor

1. Open Online Store > Themes > Customize in your Shopify admin.
2. Navigate to a product page template.
3. Click on any section or block that has a text, image, or URL setting.
4. Click the Connect dynamic source icon (looks like a small database cylinder) next to the input field.
5. Browse or search for your metafield definition.
6. Select it, and the field now dynamically pulls from that metafield for every product.

This approach requires zero Liquid knowledge. It is the recommended method for store owners using themes like Dawn, Craft, or any other Online Store 2.0-compatible theme. For more on working with theme sections, see our Shopify custom sections tutorial.

Limitations of Dynamic Sources

Dynamic sources are powerful but have constraints:

• Only works with Online Store 2.0 themes — Vintage (1.0) themes do not support this feature
• Limited formatting control — You cannot apply conditional logic or custom HTML wrappers
• One metafield per setting — Each setting field connects to exactly one dynamic source

When you hit these limitations, you move to Liquid.

---

Displaying Product Metafields with Liquid Code

For full control over how metafields render on your product pages, you write Liquid code directly in your theme files. This is where how to use Shopify metafields for products becomes a developer skill.

Basic Text Metafield

The simplest pattern wraps the metafield output in a conditional check so it only renders when a value exists:

{% if product.metafields.custom.care_instructions %}
  <div class="product-care">
    <h4>Care Instructions</h4>
    <p>{{ product.metafields.custom.care_instructions }}</p>
  </div>
{% endif %}

Always wrap metafield output in an `{% if %}` check. If a product does not have a value for that metafield, the block simply will not render — no empty headings, no broken layouts.

Number and Measurement Metafields

For numeric metafields, you can append units or format the output:

{% if product.metafields.custom.burn_time %}
  <div class="product-spec">
    <span class="spec-label">Burn Time:</span>
    <span class="spec-value">{{ product.metafields.custom.burn_time }} minutes</span>
  </div>
{% endif %}

Boolean Metafields

Boolean metafields work well for badges and conditional UI:

{% if product.metafields.custom.is_vegan == true %}
  <span class="badge badge--green">Vegan Friendly</span>
{% endif %}

File Reference Metafields (Images and PDFs)

For file references, use the image_url filter for images or link directly for documents:

{% if product.metafields.custom.size_chart %}
  <div class="size-chart">
    <h4>Size Chart</h4>
    <img
      src="{{ product.metafields.custom.size_chart | image_url: width: 600 }}"
      alt="Size chart for {{ product.title }}"
      loading="lazy"
      width="600"
    />
  </div>
{% endif %}

Product Reference Metafields

Product references let you create "related product" or "accessory" links:

{% assign related = product.metafields.custom.related_product.value %}
{% if related %}
  <div class="related-product">
    <h4>Goes Well With</h4>
    <a href="{{ related.url }}">
      <img
        src="{{ related.featured_image | image_url: width: 300 }}"
        alt="{{ related.title }}"
        loading="lazy"
      />
      <p>{{ related.title }} — {{ related.price | money }}</p>
    </a>
  </div>
{% endif %}

Notice the .value accessor — when a metafield stores a reference, you call .value to dereference it and access the linked resource's properties. For more Liquid patterns, check out our theme development beginner's guide.

---

Building a Complete Product Specs Section

Let's bring everything together with a real-world example: a reusable product specifications section that reads from multiple metafields and renders a clean table.

The Metafield Definitions

First, create these custom definitions in Settings > Custom data > Products:

The Liquid Section Code

Create a new section file or add this to your existing product template:

{% comment %} sections/product-specs.liquid {% endcomment %}

{% assign has_specs = false %}
{% if product.metafields.custom.material
  or product.metafields.custom.weight_grams
  or product.metafields.custom.country_of_origin
  or product.metafields.custom.warranty_months
  or product.metafields.custom.is_waterproof %}
  {% assign has_specs = true %}
{% endif %}

{% if has_specs %}
<div class="product-specs" id="specifications">
  <h2>Product Specifications</h2>
  <table class="specs-table">
    <tbody>
      {% if product.metafields.custom.material %}
        <tr>
          <th>Material</th>
          <td>{{ product.metafields.custom.material }}</td>
        </tr>
      {% endif %}
      {% if product.metafields.custom.weight_grams %}
        <tr>
          <th>Weight</th>
          <td>{{ product.metafields.custom.weight_grams }}g</td>
        </tr>
      {% endif %}
      {% if product.metafields.custom.country_of_origin %}
        <tr>
          <th>Country of Origin</th>
          <td>{{ product.metafields.custom.country_of_origin }}</td>
        </tr>
      {% endif %}
      {% if product.metafields.custom.warranty_months %}
        <tr>
          <th>Warranty</th>
          <td>{{ product.metafields.custom.warranty_months }} months</td>
        </tr>
      {% endif %}
      {% if product.metafields.custom.is_waterproof == true %}
        <tr>
          <th>Waterproof</th>
          <td>Yes</td>
        </tr>
      {% endif %}
    </tbody>
  </table>
</div>
{% endif %}

This section only renders if at least one spec metafield has a value. Each row is independently conditional, so the table adapts to whatever data is available. This is the pattern professional Shopify developers use to build flexible, data-driven product pages. For more on building custom sections, see our guide on how to build custom Shopify sections.

---

Accessing Metafields via the Shopify APIs

If you are building a headless storefront, a custom app, or an automated workflow, you will interact with metafields through Shopify's APIs rather than the admin UI or Liquid.

GraphQL Admin API

The GraphQL Admin API is the recommended way to create, read, update, and delete metafields programmatically. Here is an example mutation to set a product metafield:

mutation {
  productUpdate(
    input: {
      id: "gid://shopify/Product/1234567890"
      metafields: [
        {
          namespace: "custom"
          key: "burn_time"
          value: "120"
          type: "number_integer"
        }
      ]
    }
  ) {
    product {
      metafields(first: 5) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Storefront API

For reading metafields on a headless storefront (React, Next.js, Hydrogen), you use the Storefront API. Metafields must have Storefront access enabled in their definition before they appear in Storefront API queries.

query {
  product(handle: "example-candle") {
    metafield(namespace: "custom", key: "burn_time") {
      value
      type
    }
  }
}

Bulk Operations

For stores with thousands of products, use the bulk operations API or tools like Matrixify to import and export metafield values via CSV. This is far more efficient than updating products one at a time through the admin.

---

Common Mistakes and What to Avoid

Even experienced developers make mistakes with metafields. Here are the pitfalls to watch for.

1. Skipping the Conditional Check

The mistake: Outputting a metafield without wrapping it in {% if %}.

The result: Empty headings, broken layouts, or "null" text appearing on product pages that do not have a value for that metafield.

The fix: Always use a conditional wrapper:

{% if product.metafields.custom.your_field %}
  {{ product.metafields.custom.your_field }}
{% endif %}

2. Using Inconsistent Naming Conventions

The mistake: Naming metafields haphazardly — burnTime, Burn_Time, burn-time, custom.burn_time across different products or apps.

The fix: Adopt a convention and enforce it. Shopify uses snake_case for its standard definitions. Stick with snake_case for your custom definitions too. Document your naming rules and share them with your team.

3. Ignoring Standard Definitions

The mistake: Creating a custom definition for something Shopify already provides as a standard.

The result: Your metafield will not be recognized by compatible apps and themes, and you miss out on built-in formatting and validation.

The fix: Always check the standard definitions before creating a custom one.

4. Storing Display-Formatted Data

The mistake: Storing "$29.99" in a text metafield instead of 2999 in a money type metafield.

The result: You lose the ability to do math, sorting, or currency conversion. The dollar sign and decimal format are baked into the value.

The fix: Store raw data and let Liquid filters handle formatting. Use | money for prices, | date for dates, and append unit labels in the template.

5. Overloading Products with Too Many Metafields

The mistake: Creating 30+ metafield definitions on products "just in case."

The result: The product editing experience becomes overwhelming for merchants, and API calls get heavier.

The fix: Only create metafields you will actually display or use in logic. Audit your definitions quarterly and archive unused ones. A good target is fewer than 15 active definitions per resource.

6. Forgetting Storefront API Access

The mistake: Creating metafields and expecting them to appear in headless storefronts without enabling Storefront access.

The fix: In the metafield definition settings, toggle Storefront access to "Read" for any metafield you need on a headless frontend.

---

Metafields vs. Metaobjects: When to Use Which

Shopify introduced metaobjects as a companion to metafields, and the distinction trips up many merchants and developers.

Quick Comparison

When Metaobjects Make More Sense

Use metaobjects when you need:

• Reusable content shared across multiple products (e.g., a "Brand Story" used by 50 products from the same brand)
• Standalone entries that do not belong to a single product (e.g., team members, store locations, FAQs)
• Complex relationships with multiple fields grouped together

Use metafields when the data belongs to a specific product and is not shared. Most product-level customization starts with metafields. You graduate to metaobjects when the content architecture gets more complex. For more on how these concepts fit into broader theme architecture, explore our articles on app blocks vs. theme sections.

---

Tools and Apps for Managing Metafields at Scale

While the Shopify admin handles metafields well for small catalogs, stores with hundreds or thousands of products benefit from dedicated tools.

Top Metafield Management Apps

• Matrixify** — The gold standard for bulk import/export. Supports metafields across all resource types via Excel and CSV. Essential for migrations and large catalog updates.
• Metafields Guru — Provides a spreadsheet-like interface for editing metafield values in bulk, with JSON support for complex types.
• Accentuate Custom Fields — Adds advanced field types and a polished editing UI. Popular with agencies building client stores.

Shopify CLI and Theme Development

If you are building or customizing themes, the Shopify CLI lets you pull theme files locally, edit Liquid, and push changes back. Combined with the metafield definitions you set up in the admin, this is the professional workflow for Shopify development.

CSV Bulk Imports

Shopify's native CSV import supports a limited set of metafield columns. For full metafield control via CSV, Matrixify is the de facto tool. It lets you map columns to specific namespace-key pairs and handles type validation during import.

---

Real-World Use Cases for Product Metafields

Knowing the mechanics is only half the battle. Here are concrete use cases organized by industry to spark ideas for your own store.

Fashion and Apparel

• Fabric composition — single_line_text_field showing "80% Cotton, 20% Polyester"
• Care instructions — Standard definition for washing/drying guidance
• Size chart — file_reference linking to a PDF or image
• Model measurements — multi_line_text_field with height, chest, waist of the model photographed

Food and Beverage

• Ingredients list — Standard definition or multi_line_text_field
• Allergen warnings — list.single_line_text_field for multiple allergens
• Expiration date — date type for freshness tracking
• Nutritional information — json type for structured macro data

Home and Garden

• Burn time — number_integer for candles
• Assembly required — boolean flag
• Dimensions — dimension type for length, width, height
• Warranty period — number_integer in months

Electronics and Tech

• Compatibility list — list.product_reference linking to compatible devices
• Voltage — single_line_text_field like "110-240V"
• Certification badges — list.file_reference for CE, FCC, UL images
• Firmware version — single_line_text_field for current version

For guidance on setting up your product catalog efficiently, see our article on how to add products to Shopify and our inventory management best practices.

---

Testing and Validating Your Metafields

Once you have set up definitions, entered values, and written Liquid code, you need to verify everything works correctly across your storefront.

Pre-Launch Checklist

1. Check products with values — Visit a product page where metafield values are populated and confirm each one renders correctly.
2. Check products without values — Visit a product that has no metafield values entered. Confirm nothing breaks — no empty headings, no layout shifts, no "null" text.
3. Test on mobile — Metafield sections like specs tables and size chart images must be responsive.
4. Validate data types — Enter an intentionally wrong value (text in a number field) and confirm Shopify's admin validation catches it.
5. Check Storefront API access — If you are headless, query the Storefront API and verify metafield values return correctly.

Debugging Tips

• Metafield not showing? Check the namespace and key in your Liquid code match exactly what you defined in the admin. Typos here are silent — no error, just empty output.
• Getting "null" or empty output? Use {{ product.metafields.custom.your_field | json }} to dump the raw value and inspect the data type.
• Reference metafield not resolving? Make sure you are calling .value on the metafield to dereference it: product.metafields.custom.related_product.value.title.

---

Conclusion

Learning how to use Shopify metafields for products is one of the highest-leverage skills you can develop as a Shopify merchant or developer. Metafields let you break free from the constraints of the default product editor, attach rich custom data to every product, and display that data with pixel-perfect control in your theme.

Start with standard definitions for common fields like care instructions and ingredients. Move to custom definitions for store-specific data like burn times or warranty periods. Use dynamic sources in the theme customizer for no-code implementations, and graduate to Liquid when you need full control over conditionals, formatting, and layout.

The key is to start small. Pick one or two metafields that would immediately improve your product pages, set them up, connect them to your theme, and expand from there. Before long, you will have a product data architecture that scales with your catalog and gives your customers the information they need to buy with confidence.

Have questions about metafields or want to share how you are using them in your store? Join the Let's Talk Shop community — our Shopify experts network is always ready to help you level up your store.

---

*Want to dive deeper into Shopify development? Browse our full collection of tutorials and guides on the Let's Talk Shop blog.*

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.