Shopify metafields are custom fields you add to products, collections, customers and other resources to store data Shopify has no built-in field for: care instructions, ingredients, sizing tables, spec sheets, delivery windows. Creating them takes two minutes in the admin. Getting them onto your storefront is the part nobody explains, and it is where most merchants stall.
This covers both halves, plus the limits and the one naming trap that returns a wrong value instead of an error.
What are metafields in Shopify?
A metafield is a named piece of custom data attached to a Shopify resource, addressed by a namespace and a key. Shopify gives every store the same fixed fields (title, price, description, weight). A metafield is how you add the field your catalogue actually needs and Shopify never shipped.
The parts that matter:
- Owner resource - what it is attached to: product, variant, collection, customer, order, page, blog, article, shop, or a metaobject.
- Namespace - a grouping that prevents collisions, so your
specs.materialand an app'sspecs.materialnever overwrite each other. - Key - the field name.
- Type - what it holds, and this is a real type system rather than a free-text box: single line text, rich text, integer, decimal, date, dimension, weight, volume, rating, colour, URL, JSON, plus references to files, products, pages, and metaobjects.
- Definition - the schema. Defining a metafield gives it validation, makes it appear in the admin UI, and is what turns it from a hidden value into something a merchant can actually edit.
Metafield versus metaobject, since the two get confused: a metafield adds a field to something that already exists. A metaobject is a whole custom record type you invent, like "Ingredient" or "Size chart", which metafields can then point at.
Metafields vs tags: which should you use?
The main difference between metafields and tags is structure: tags are a flat list of strings with no type and no schema, while metafields are typed, named, validated fields. Tags exist to filter and group. Metafields exist to store and display information.
The practical rule: if you would ever want to show the value on the page, it is a metafield. If you only want to find products by it, a tag is lighter. "Material: merino wool" belongs in a metafield because it goes on the product page. "sale" belongs in a tag because it only drives a collection.
Where people get this wrong is stuffing display data into tags because tags are easier to bulk edit. It works until you need to render Material: merino wool and find yourself parsing strings in Liquid.
How to add metafields in Shopify
The admin route, no code required:
- Settings > Custom data, pick the resource type (Products, Variants, Collections, and so on).
- Add definition. Give it a name, a namespace and key, and a type. The type matters more than it looks: picking "single line text" for a number means you cannot sort or validate it later.
- Set validation where it helps: minimum and maximum, allowed values, required.
- Pin it if merchants will edit it often. Pinned definitions appear directly on the product page in the admin instead of behind a link. You get 50 pinned per resource type.
- Fill in values on individual products, or in bulk through the bulk editor, a CSV import, or the Admin API.
At this point the data exists and your storefront still shows nothing. That is expected, and it is the step most guides skip.
How to display metafields on your theme
Two routes, and which one you can use depends on your theme.
Through the theme editor, if your theme supports dynamic sources: add a text or rich-text block to the product template, click the dynamic source icon, and pick your metafield. No code, and it is the right answer for most merchants.
In Liquid, when you need control over the markup:
{{ product.metafields.specs.material }}
{{ product.metafields.specs.material.value }}
{{ product.metafields.specs.material.type }}
Always guard it, because a product without that metafield renders an empty label:
{% if product.metafields.specs.material %}
<p><strong>Material:</strong> {{ product.metafields.specs.material.value }}</p>
{% endif %}
For json metafields, .value returns an object you can read by name or index, and iterate:
{{ product.metafields.specs.dimensions.value.width }}
{% for property in product.metafields.specs.dimensions.value %}
{{ property.first | capitalize }}: {{ property.last }}
{% endfor %}
The naming trap that returns a wrong value
If your metafield key is size, first or last, dot notation silently breaks. Those are Liquid filter names. Written as product.metafields.specs.size, Liquid returns the metafield when it exists, but when it is missing it applies the filter to the namespace instead, so you get the metafield count rather than an empty value.
The fix is bracket notation, which always looks up by key:
{{ product.metafields.specs["size"] }}
This is worth knowing because it fails by printing a plausible number rather than by erroring, which is the worst way for a bug to behave. Shopify documents it in the metafield Liquid object reference.
The real limits
Per Shopify's metafield limits documentation:
| Limit | Value |
|---|---|
| Merchant definitions, per resource type | 256 |
| App definitions, per resource type, per app | 256 |
| Pinned definitions, per resource type | 50 |
| Most metafield types, size | 64 KB |
json type, size |
128 KB |
id and url types, size |
2 KB |
| Predefined choices on single-line text | 128 values |
| List types, items | 128 (metaobject references: 1,024) |
| Definitions powering smart collections | 128 |
| Definitions usable as an admin filter on products | 50 |
| Definitions usable as an admin filter on orders | 5 |
Standard metafield definitions, the ones Shopify ships for common categories, do not count toward those limits.
One trap for anyone building with Shopify Functions: function input queries do not return metafield values larger than 10,000 bytes. The value is stored and the Admin API still returns it, but your function receives null. Nothing warns you.
When metafields are the wrong tool
Being honest about the boundary saves rework:
- Data that belongs to a whole category of things, not one product, is a metaobject. Build "Size chart" once and point twenty products at it, rather than pasting the same table into twenty metafields.
- Anything you need to filter or sort on at scale. Metafields can power smart collections and admin filters, but with hard caps (128 and 50 respectively). If filtering is the primary job, design for it up front.
- Frequently changing operational data. Metafields are content, not a message queue. Rapid successive writes can race, with later updates overwriting earlier ones.
Where the theme becomes the ceiling
Storing the data is the easy half. Rendering it well is where it stops: a spec table that matches your brand, a care-instructions accordion, an ingredient list with the right typography. If your theme has no block for it, you are editing Liquid, hiring someone, or installing an app.
That is the same wall covered in our Dawn customization limits piece, and it has the same three answers. The fourth, newer one: describe the section you want, including which metafields it should read, and generate it as real Liquid. The output is a theme section with a proper schema, reading your metafields, in files you own.
FAQ
What is an example of a metafield in Shopify?
A care-instructions field on a product: namespace information, key directions, type single line text, value "Take with a meal." You would display it with {{ product.metafields.information.directions.value }}. Other common ones are ingredients, materials, size charts, warranty length and delivery estimates.
How many metafields can we create in Shopify? Merchants can create up to 256 metafield definitions per resource type, and each installed app gets its own 256 per resource type. Of yours, 50 can be pinned to appear directly in the admin editor. Shopify's standard definitions do not count toward the limit.
What is the difference between metafields and tags in Shopify? Tags are untyped strings used for grouping and filtering. Metafields are typed, named, validated fields meant to store and display information. If the value should appear on the page, use a metafield; if it only needs to drive a collection or a filter, a tag is lighter.
What is the difference between product metafields and category metafields? Product metafields are defined by you and apply to whatever products you fill in. Category metafields come from Shopify's standard product taxonomy: define them once and they apply automatically to products in that category, with the validation Shopify already specified. Use category metafields where they exist, since they do not count toward your definition limit.
Do metafields work with the Storefront and GraphQL APIs? Yes. Metafields are readable through the Storefront API for headless builds and readable and writable through the GraphQL Admin API, which is also how bulk imports and exports are usually done at scale.
Why is my metafield not showing on the storefront?
Three usual causes, in order of likelihood: the definition exists but the value is empty on that product; the theme has no block or Liquid outputting it, since creating a metafield never displays it automatically; or the key collides with a Liquid filter name (size, first, last) and needs bracket notation.
Keep reading: the Shopify Liquid cheat sheet and how Shopify theme development actually works.