Skip to main content

Shopify Metafields and Metaobjects: A Practical Guide

  • November 1, 2026
  • 7 min read
  • By CYPHEX
Shopify Metafields and Metaobjects: A Practical Guide

Shopify metafields are how you add the facts your product pages are missing: ingredients, materials, size charts, care steps, delivery notes. This guide is for store owners and marketers who want that detail on the page, and for technical leads who have to plan the data behind it. You will leave knowing the difference between metafields and metaobjects, how to plan a content model, how the data reaches a theme, and where the limits bite.

What are Shopify metafields and metaobjects?

Shopify’s custom data docs draw the line cleanly.

A metafield adds a field to something that already exists: a product, variant, collection, order or customer. “Skin type” on a product is a metafield.

A metaobject is a record type you invent, for information that does not belong to one existing object. An “Ingredient”, a “Store location” or an “FAQ entry” would each be a metaobject, with fields of their own.

In practice you use them together. The metaobject holds the reusable thing, and a metafield on the product points to it. Change the ingredient once and every product that references it changes too.

Definitions: the step people skip

Both start with a definition: a name, a namespace and key, a type and optional validation rules. A defined metafield gets a proper editor in the admin and checks values as they are saved. An undefined one is stored as a plain string, which nobody can validate or search. If it is worth storing, it is worth defining.

On types, Shopify’s docs and Liquid reference show text, numbers, dates, URLs, JSON, files and references to products, collections, variants, pages and metaobjects, and many can be lists. The list of data types changes over time, so read it before you commit to a design. The rule I would apply: pick the narrowest type that fits. A reference to an Ingredient entry beats a comma-separated text box every time, because you can link to it, reuse it and fix it in one place.

Where they earn their keep

UseHow to model it
Product specsMetafields: material, dimensions, warranty
Size guidesA “Size chart” metaobject, referenced from products
FAQsAn “FAQ” metaobject (question, answer), referenced as a list
Store locatorA “Store” metaobject: address, hours, phone
Ingredient listsAn “Ingredient” metaobject, list-referenced on products
B2B infoCustomer or company metafields for terms and notes
BadgesA true/false or list metafield that the theme turns into a label

For a more advanced use, where metafields drive configurable products, see custom product builders with metafields.

Showing the data in your theme

There are two routes, and the first one needs no code.

Dynamic sources. If your theme supports them, you connect a text block or setting to a metafield in the theme editor and the value fills in per product. Shopify’s help says you can connect most metafields this way, and that types your theme does not support need code. Older themes may not offer it.

Liquid. In templates you read a metafield through its namespace and key, as the Liquid metafield reference shows:

{% comment %} "custom" and "skin_type" are example names from our own model {% endcomment %}
{% if product.metafields.custom.skin_type != blank %}
  <p>Skin type: {{ product.metafields.custom.skin_type.value }}</p>
{% endif %}

{% comment %} A list of single-line text values {% endcomment %}
{% for item in product.metafields.custom.key_benefits.value %}
  <li>{{ item }}</li>
{% endfor %}

Reference types return the object they point to, so you can read its fields. For the exact syntax with metaobjects, use Shopify’s metaobject documentation rather than guessing. And always test for blank values, otherwise an empty field leaves a heading with nothing under it.

How apps and custom apps read and write them

Apps read and write both through the Admin GraphQL API, and storefronts can read them through the Storefront API. The docs say apps own their definitions in a reserved namespace so they do not collide with yours, that merchants can edit app data in the admin if the definition is made visible, and that Shopify Functions, extensions and Analytics can read the data too. Analytics needs the definition to be marked analytics-queryable.

The usual use for a custom app is syncing: specs from a supplier sheet or PIM, delivery dates from an ERP. Our Admin API and webhooks guide covers the build. Grant only the access scopes the job needs.

Planning a content model before you create anything

Start with customer questions, not with fields. Write down what buyers ask before they purchase: what is it made of, will it fit, how do I use it, can I return it.

Then sort each answer. Does it belong to one product, is it shared across many, or does it belong to a place? One product suggests a metafield, shared suggests a metaobject, a place suggests a Store entry. Decide who edits each field and which system wins when two disagree. Use lower-case keys with clear namespaces and no spaces.

Begin with three to five fields that reduce returns or answer sales questions. You can always add more. What you cannot easily do is clean up forty fields nobody remembers creating.

What this does for SEO

Metafields do not rank anything by themselves. What they give you is consistency: every product shows the same specs in the same order, written once instead of pasted into hundreds of descriptions. That helps shoppers and makes pages easier to understand, and it gives you clean data for Product structured data such as brand, SKU or GTIN. Mark up only what the page visibly shows, and do not expect any rich result as a guarantee. Related reading: schema markup basics and our Shopify SEO checklist.

Limits and pitfalls

Shopify’s metafield limits cover definition counts and value sizes. From the published pages: most text types cap at 65,000 characters, list types hold at most 128 items (metaobject reference lists go to 256), and a metaobject definition can have up to 40 fields. Other numbers, such as definition counts and entries, have been revised between versions of the docs, so check the live pages before sizing a large catalogue.

Common mistakes:

  • Leaving metafields undefined, then wondering why filtering and validation do not work.
  • Hard-coding a key in the theme, then breaking the page when someone renames the field.
  • Using a type the theme cannot display, and getting a blank space.
  • Keeping the same facts in a metafield and in the description, so they drift apart.
  • Putting private notes where the storefront can read them. Check access settings first.

Worked example: a skincare store (illustrative)

Take a made-up skincare shop that wants an ingredient list, a “key ingredients” highlight and skin-type badges.

  1. Create a metaobject definition called Ingredient with fields for name, plain-English purpose, INCI name and a link to a glossary page.
  2. Add a product metafield ingredients as a list of Ingredient references, and skin_type as a list of text values with preset choices.
  3. Create each ingredient entry once, for example niacinamide.
  4. On every product, pick ingredients from the list. Editing an ingredient’s description updates every product that uses it.
  5. In the theme, show the list in a tab, link each name to its glossary page, and turn skin types into badges or filters.
  6. Reuse the same fields for brand and key facts in your Product structured data.

Cosmetic labelling rules vary by country. Keep the legal ingredient list under your compliance process, and treat this model as a way to display it, not to decide it. For conversion ideas in this niche, see Shopify skincare conversion.

Frequently Asked Questions

What is the difference between a metafield and a metaobject?

A metafield adds a field to an existing resource such as a product. A metaobject is its own record type, such as an ingredient or a store, that many products can point to.

Do I need a developer to use metafields?

Not always. With a theme that supports dynamic sources you can connect many metafields in the editor. Custom layouts, unsupported types and large imports usually need Liquid or an app.

Can I bulk edit or import metafield values?

Often yes, but how depends on your admin and tools. Check what Shopify’s bulk editor and import cover for your store, and consider the Admin API or an app for large catalogues. Try a handful of products first.

Are metafields visible to customers?

Only when a theme or app displays them or the storefront is allowed to read them. Do not store private information in a field the storefront can reach.

Will metafields improve my rankings?

Not directly. They help you publish consistent, useful, structured content, which supports SEO but is not a shortcut.

Conclusion

Shopify metafields and metaobjects turn scattered product facts into structured content you can reuse, validate and display consistently. Plan the model around real customer questions, define every field, and write theme code that copes with blanks. If you would like help with this, CYPHEX can plan and deliver it for you, with one project lead as your contact. You can also read about our Shopify services.

Stock photography provided by Pexels under the Pexels License.

Want your online store to sell more?

We can review your store and show you what to fix first to turn more visitors into buyers.

Comments

  1. Loading comments...

Leave a comment

Selling online?

Turn more visitors into orders

A faster, clearer store with better product pages and checkout. We handle Shopify and WooCommerce from setup to growth.

Step 1 of 3

Tell us what you need

Three quick steps. We reply within one business day.

What do you need help with? Pick all that apply