What Is a Shopify Metafield?
A Shopify metafield is a custom data field you attach to a store object such as a product, variant, collection, customer, or order to store information the default fields do not cover. Examples include a product's material, wash instructions, size chart, or a downloadable spec sheet. Metafields have a defined type, a namespace, and a key, and you can display their values in themes with Liquid or read them through the Storefront API. They let you build richer, more structured storefronts without hacking the product model.
- What it is
- A custom field for storing extra structured data on Shopify objects (Shopify.dev)
- Where they attach
- Products, variants, collections, customers, orders, pages, and more
- Structure
- Each has a type, namespace, and key, e.g. custom.material of type single_line_text
- Types
- Text, number, date, JSON, file reference, product reference, rich text, and others (Shopify.dev)
- Access
- Readable in Liquid themes and via the Storefront and Admin GraphQL APIs
- Related
- Metaobjects group multiple metafields into reusable custom content types
What a Shopify metafield is #
A Shopify metafield is a custom data field that stores extra information on a store object when the built-in fields are not enough. Every product already has standard fields like title, price, and description, but real catalogs often need more: a fabric composition, care instructions, a warranty length, a downloadable manual, or a highlight badge. Metafields let you add exactly those pieces of structured data without misusing the description or cramming details into tags. Each metafield attaches to a specific object type, most commonly products and variants, but also collections, customers, orders, and pages. It has a defined data type, a namespace to group related fields, and a key to identify it. Because the data is structured and typed, you can display it cleanly in your theme and reuse it across pages. This is a core tool when we build tailored storefronts under /services/shopify-web-design, especially for catalogs with rich specifications that standard fields cannot capture properly.
Why metafields matter #
Metafields matter because they let you model your specific business data instead of forcing everything into Shopify's generic fields. A furniture store needs dimensions and materials; a supplement brand needs ingredients and dosage; an electronics seller needs voltage, warranty, and a downloadable datasheet. Without metafields, that information ends up buried in the description as unstructured text, which is hard to display consistently, filter by, or reuse. With metafields, each attribute is a discrete, typed value you can render exactly where you want, style uniformly across every product, and even use to build comparison tables or spec sections. Structured data also feeds richer experiences: dynamic size charts, conditional badges, and content that changes per product without editing the theme each time. For headless and custom builds, metafields are essential because they expose clean data through the API. We use them heavily in /services/ecommerce-development to turn a generic template into a storefront that reflects a brand's actual product complexity.
Metafield structure: type, namespace, key #
Every metafield has three defining parts. The type controls what kind of value it holds and how Shopify validates it, for example single line text, multi-line text, integer, decimal, date, boolean, JSON, rich text, a file reference for PDFs or images, or a reference to another product or collection. Choosing the correct type matters because it enforces valid data and unlocks the right input in the admin. The namespace is a grouping label that keeps your fields organized and prevents collisions, often something like custom or specs. The key is the unique name of the field within that namespace, such as material or wash_instructions. Together they form an identifier like custom.material. Modern Shopify uses metafield definitions, which let you predefine a field's type, name, and validation so it appears as a proper labeled input on every product rather than as loose ad-hoc data. Setting up clean definitions up front is what keeps a metafield strategy maintainable as a catalog grows.
Example: displaying a metafield in Liquid #
Once a metafield exists, you display its value in your theme with Liquid using its namespace and key. The snippet below reads a product's material metafield and renders it only if a value is present, which prevents empty labels on products that lack the data.
{% if product.metafields.custom.material %}
<p class="product-material">
<strong>Material:</strong>
{{ product.metafields.custom.material.value }}
</p>
{% endif %}
{%- comment -%} File-type metafield, e.g. a spec sheet PDF {%- endcomment -%}
{% if product.metafields.custom.spec_sheet %}
<a href="{{ product.metafields.custom.spec_sheet.value.url }}">Download spec sheet</a>
{% endif %}Common uses for metafields #
Metafields solve a wide range of real merchandising needs. Common product uses include material and care instructions, dimensions and weight beyond shipping data, ingredient lists, warranty terms, sizing details, downloadable manuals or spec sheets, and highlight badges like Vegan or Made in USA. On collections, metafields can store a banner image, a category-specific promo message, or SEO copy. On customers, they can hold loyalty tier, preferences, or B2B account attributes. On orders, they can capture custom instructions or integration references. Because metafields are structured, you can render them consistently: a specifications table that looks identical on every product, or a conditional badge that only appears when a flag is set. This structure also enables filtering and richer search in some setups. For merchants integrating with external systems, metafields often mirror data from a PIM or ERP, which we sync through /services/api-crm-integrations so product information stays accurate across every channel without manual re-entry in Shopify.
Metafields and the Storefront API #
For custom and headless storefronts, metafields are how you expose brand-specific product data to a decoupled frontend. The Storefront API can return metafield values through GraphQL, so a React, Next.js, or Hydrogen front end can request exactly the fields it needs, such as material, warranty, or a spec sheet URL, and render them however the design requires. This is essential because a headless build does not use Liquid, so metafields become the structured bridge between Shopify's catalog and your custom UI. To be readable through the Storefront API, metafields generally need to be marked as storefront-visible via their definition. Planning which metafields the frontend needs is part of architecting a headless store, and it directly affects performance and maintainability. We design this data layer during headless and custom /services/web-app-development projects so the frontend receives clean, typed data rather than parsing unstructured text, which keeps the storefront fast and the codebase easy to extend as products evolve.
Metafields vs metaobjects #
Metafields and metaobjects are related but serve different purposes. A metafield adds a single custom field to an existing object like a product. A metaobject is a custom content type you define from scratch, grouping several fields into a reusable structured record that does not belong to one specific product. For example, you might create a metaobject for a designer profile with name, bio, and photo, then reference that single metaobject from many products by the same designer. This avoids duplicating the same data on every product. Metaobjects are ideal for reusable content such as size guides, ingredient definitions, store locations, or care instruction sets shared across items. You connect products to metaobjects using a reference-type metafield. Together they let you model fairly complex, relational content entirely inside Shopify without a separate CMS. Deciding when to use a simple metafield versus a shared metaobject is an architecture choice we make early, because it strongly affects how easy the store is to maintain later.
Metafields and third-party apps #
Many Shopify apps read and write metafields, which makes them a shared data layer across your store rather than a purely manual feature. Product review apps, for instance, may store ratings in metafields; subscription and bundle apps use them to hold configuration; and page-builder apps often let you bind sections to metafield values so content updates automatically when the data changes. This means metafields you create can power app-driven features, and app-created metafields can be surfaced in your theme. It also means a consistent namespace strategy matters even more, so your fields and app fields do not collide or confuse editors. When migrating between apps or platforms, metafields are frequently where custom product data lives, so mapping them correctly is critical to avoid losing information. Because metafields increasingly connect your catalog to external systems, we treat them as an integration surface, syncing them with PIMs, ERPs, and marketing tools through /services/api-crm-integrations so product data stays accurate and consistent everywhere it is used.
Getting started with metafields #
To use metafields well, start with definitions rather than ad-hoc entries. In the admin, create a metafield definition for each attribute you need, choosing the correct type and a clear namespace and key, so every product shows a proper labeled input. Decide which fields the storefront must display and which are internal, and mark storefront-visible ones accordingly if you plan to use the Storefront API. Then update your theme, or your headless frontend, to render those fields cleanly with fallbacks for missing values. Avoid overloading products with dozens of rarely used fields, and reuse metaobjects for shared content. Keep a simple document of your namespaces and keys so the team stays consistent. Done properly, metafields transform a generic template into a storefront that reflects your real products, improves clarity for shoppers, and feeds accurate data to every channel. If you want a structured product data model set up correctly from the start, talk to us at /contact or review your current setup at /free-website-audit.
FAQ
What is a metafield used for in Shopify?
A metafield stores custom data that Shopify's standard fields do not cover, such as a product's material, dimensions, warranty, ingredients, or a downloadable spec sheet. You attach it to objects like products, collections, or customers, then display the value in your theme or read it through the API to build richer, more informative storefronts.
What is the difference between a metafield and a metaobject?
A metafield adds one custom field to an existing object like a product. A metaobject is a reusable custom content type that groups several fields into a standalone record, such as a size guide or designer profile, which many products can reference. Use metafields for single attributes and metaobjects for shared, relational content.
How do I display a metafield on my product page?
In a Liquid theme you reference the metafield by namespace and key, for example product.metafields.custom.material.value, wrapped in a conditional so empty fields do not render. Some themes also let you add metafields to product pages through the theme editor. In headless stores, you fetch the value through the Storefront API and render it in your frontend.
Can the Storefront API read metafields?
Yes. The Storefront API can return metafield values via GraphQL, which is how headless and custom storefronts access brand-specific product data. The metafield usually needs to be marked storefront-visible through its definition. This lets a React, Next.js, or Hydrogen frontend request exactly the fields it needs and render them in a custom UI.
What types of data can a metafield hold?
Metafields support many types, including single and multi-line text, integers, decimals, dates, booleans, rich text, JSON, file references for PDFs or images, and references to other products or collections. Choosing the correct type enforces valid data and gives the right input in the admin, which keeps your custom product data clean and reliable.
Do I need a developer to use metafields?
Not always. You can create metafield definitions and enter values directly in the admin, and many modern themes let you display common metafields through the theme editor without code. A developer is helpful when you need custom Liquid display, conditional logic, metaobjects, or Storefront API integration for headless builds, which is where a tailored setup pays off.
How Local Web Advisor checks this for you
Is your own website getting e-commerce right?
Our free AI audit scans your site and tells you — in plain English — exactly what to fix for e-commerce and seven other areas, with the business impact and the fix for each. No login needed to start.
Run my free website audit →Was this helpful?