Shopify Metafields: A Plain-English Guide With Examples

Shopify metafields are custom fields for information Shopify has no built-in field for, attached to a part of your store such as a product, variant, collection, customer or order. Think of a T-shirt's care instructions, a sofa's dimensions or a customer's loyalty tier. You create a metafield definition (a name, a namespace and key, and a content type) under Settings > Metafields and metaobjects, fill in a value on each record, then show it on your storefront by connecting it to a theme block, or use it in collections, storefront filters, customer segments and reports. Metafields are built into Shopify admin, so you don't need an app to start.

Most of Shopify's help pages call that area Settings > Metafields and metaobjects; a few still say Settings > Custom data. Use whichever your admin shows. Steps below follow Shopify's Help Center as of October 2026.

What are metafields in Shopify?

A metafield is a labelled slot for one piece of data on one record. Shopify's metafields overview describes them as a way to extend Shopify's existing data model with your own custom data. The standard product form covers a title, description, price and media. Anything else customers or staff need, such as an ingredient list, a recommended age or a warranty period, can live in a metafield. Check for a built-in field first: barcodes such as UPCs and EANs have their own field on each variant, as our guide to Shopify barcodes explains.

Every metafield has three parts:

• A definition: the template that names the field, ties it to one part of the store and sets which values it accepts.
• A namespace and key: the field's unique identifier, written with a period, such as custom.care_instructions. Shopify's definition parts guide says both can contain only letters, numbers, underscores and hyphens.
• A value on each record: such as "Machine wash cold" on one T-shirt and "Hand wash only" on another.

Typical examples, most taken from Shopify's own overview:

What are product metafields in Shopify?

Product metafields are metafields whose definition belongs to Products: every product gets the same field, and each product stores its own value. They are the most common kind, because product pages need the most extra detail. Variant metafields hold a value per variant instead, such as the garment length of each size. Use them only when the value really changes between variants, or you multiply the data entry. Shopify's variants guide also says variant metafields can't be displayed to customers at this time, though storefront filters can use them. A detail that doesn't change a variant's price, SKU or stock can live in a product metafield instead of taking one of a product's three options, as our Shopify variant limit guide explains.

Two practical differences matter later. Shopify's CSV guide says defined product metafields are included in product CSV exports and imports, but variant metafields aren't supported in CSV files. And category metafields are a special set of product metafields tied to the product's category, covered below.

Which parts of a Shopify store can have metafields?

Shopify's developer reference lists every metafield owner type. It includes products, variants, collections, customers, orders, draft orders, pages, blogs, blog posts, markets, locations, and B2B companies and company locations, plus the shop itself and app-facing resources such as discounts, selling plans, and delivery and payment customizations, which apps usually manage for you.

Market metafields suit content that differs by country or region: since April 2024 the theme editor can use them as a dynamic source.

What's the difference between defined and unstructured metafields?

Shopify's custom data overview separates metafields with definitions, which are standard or custom, from unstructured and app-owned metafields:

The definition is what makes a metafield useful. Shopify's developer overview of custom data says a defined metafield gets a typed editor in admin, validation when values are written, and search and filtering, while an undefined one is stored as a plain string. Shopify recommends a standard definition whenever one fits (adding metafield definitions).

A definition holds a name, a namespace and key, an optional description, a content type, optional validation rules and options that control where the field can be used, such as storefronts, collections, admin filters and analytics. After you save a custom definition, Shopify's editing guide lists its name, description and validation rules as editable, along with options such as storefront access and pinning. The type isn't on that list, so choose it with care. Shopify's metafield limits allow 256 merchant definitions per part of the store, such as products or customers; standard definitions don't count toward that limit unless Shopify says otherwise.

What to do with unstructured metafields

To see them, go to Settings > Metafields and metaobjects, choose a part of the store such as Products, and click View unstructured metafields (it may sit under More actions). To migrate one, click Add definition next to its namespace and key, choose a type, click Save, then review the validation results and click Save definition.

Shopify's migration guide adds two cautions. Define only namespaces and keys you recognize, because a definition can stop an app that relies on them from working as expected. And namespaces or keys with special characters can't be migrated.

What are the Shopify metafield types?

The type decides what a field can hold, which input admin shows and where the value can go in your theme. Shopify's content types reference groups them like this:

Most types can also be a list of values, such as several product references. Multi-line text, Rich text, True or false, Money, ID and JSON can't. Lists hold up to 128 items, or 1,024 for metaobject references, and single line text can offer up to 128 preset choices (metafield limits).

Which metafield type should you choose?

• Shoppers should filter by it: use Single line text (ideally with preset choices), Integer, Decimal, True or false, or a Metaobject reference, the types Search & Discovery filters accept.
• It should build automated collections: use Single line text, True or false, Integer, Decimal or Rating, or a Metaobject reference, which smart collection conditions have accepted since December 2024.
• It's a number with a unit: use a measurement type rather than text, so values stay consistent and comparable.
• It's a formatted paragraph: use Rich text if your theme block accepts rich text, Multi-line text otherwise.
• It's a structured item reused across many products, such as a size chart, an FAQ or an icon with a caption: build a metaobject and reference it. Our guide to Shopify metaobjects explains when that beats a plain metafield.

Validation rules depend on the type, from character limits and regular expressions to number ranges and allowed URL domains. Start loose: a value that breaks a rule can't be saved, and when you create a definition over existing values that don't fit, Shopify lists them as invalid and shows Fixes needed until you correct them. Our guide to fixing metafield validation errors shows the cleanup.

How to add metafields in Shopify

Step 1: Create the definition

These steps follow Shopify's guides to standard definitions and custom definitions:

1. From your Shopify admin, go to Settings > Metafields and metaobjects.
2. Choose the part of your store, such as Products, and click Add definition.
3. In Name, type what the field is for, such as "care" or "rating". If Shopify suggests a matching standard definition, click it: the name, namespace and key, description and type fill in.
4. For a custom definition, check the generated Namespace and key, click Select type and choose one, such as Single line text or File.
5. To accept several values, change One value to List of values.
6. Optionally add a description and Validation rules.
7. Review the options, such as storefront access and collections, and whether the definition stays pinned.
8. Click Save.

You can also start from a record: open a product or customer and click Add definition in its Metafields section.

Step 2: Fill in the values

Open the product, collection, customer or other record, go to its Metafields section, click a field, enter a value and click Save (adding values to metafields). Only pinned definitions show automatically; click View all for the rest. You can pin up to 50 definitions per part of the store, so pin the fields your team fills most.

For many records at once:

• Bulk editor: go to Products, select products, click Bulk edit (Shopify's metafields guide calls it Edit products), then Columns, and pick fields in the Metafields section. Shopify supports bulk editing metafields for products, variants, collections and customers. Our Shopify bulk editor guide covers the workflow and its limits.
• CSV import: Shopify's CSV guide gives product metafield columns the header Name (product.metafields.namespace.key), and its list examples separate values with a semicolon and a space. With Overwrite products with matching handles selected, a blank cell in a non-required column clears the saved value, so read our product CSV update checklist before importing.

How to use metafields in Shopify

How do you show metafields on product pages?

Use the theme editor's dynamic sources: when you connect a metafield to a theme setting, the theme pulls each product's own value. Shopify's sections and blocks guide gives these steps:

1. In Shopify admin, go to Online Store, find your theme and click Edit theme.
2. Use the template drop-down at the top, which starts on Home page, to open the template you want, such as your default product template.
3. Select the section or block, such as a text block in the product information section.
4. Click the dynamic source button (a database icon) beside the setting and pick the metafield.
5. Click Save, then preview one product with a value and one without.

What decides whether this works:

• Theme: dynamic sources need a theme that supports JSON templates, and not every section or block supports them. With other themes, showing a metafield means editing theme code.
• Storefront access: Shopify's options for custom data say Storefronts access makes a metafield available through Liquid or the Storefront API.
• Type and setting must match: Shopify's dynamic sources reference shows which types each setting accepts. Text settings take single line text, number, date, weight, volume, dimension, rating and money metafields; multi-line text fits only rich text settings; and file references fit image or video settings.
• Up to 20 per template: when the dynamic source icon shows a +, you can add up to 20 metafields to a template, according to Shopify's displaying metafields guide.
• Category metafields become available only once the product has a category assigned, per the same sections and blocks guide.

How do you show a metafield with Liquid?

If no block fits, a developer can output the value in theme code. This example prints a care instructions field only when the product has one:

{% if product.metafields.custom.care_instructions.value != blank %}
  <h3>Care instructions</h3>
  {{ product.metafields.custom.care_instructions | metafield_tag }}
{% endif %}

Shopify's metafield object reference explains the pattern: resource.metafields.namespace.key, with .value for the stored value. The metafield_tag filter wraps a value in HTML suited to its type. Keys named size, first or last need bracket notation. Shopify's metafield limits add that a loop over a reference list returns only the first 50 items unless you paginate. Duplicate your theme before editing code.

How do you filter products by metafield?

Storefront filters are built in Shopify's free Search & Discovery app, so install it first if it isn't in your Apps list. Then:

1. Go to Apps > Search & Discovery.
2. Click Filters, then Add filter.
3. Click Source and choose a product, variant or category metafield.
4. Optionally rename the filter or group its values, then click Save.

Shopify's filters guide lists the supported types: Single line text, Integer, Decimal, True or false and Metaobject reference, with lists of single line text and metaobject references. A store can have up to 25 filters, the storefront shows up to 100 values per filter, and collections with more than 5,000 products don't show filters. To check theme support, go to Content > Menus: an unsupported theme shows a message in the Collection and search filters section, and customers won't see the filters you create.

Where else can you use metafields?

• Automated collections: turn on the collections option in a product or variant definition, then open a collection and click Add condition > Metafield. Shopify's collections with metafields guide allows this for up to 128 definitions.
• Admin filters: turning on the product index filter option lets you filter the Products list by up to 50 metafield definitions, and the orders list allows 5 (filtering products and options for custom data).
• Customer segments: customer metafields of date and time, number, text, or true or false type can be segment filters, such as metafields.custom.points_balance >= 100.
• Reports: per the options for custom data, Filter or group data in Analytics lets a product, variant, customer or order metafield act as a report filter or dimension, such as total sales by material.
• Shopify POS: Shopify's metafields overview says POS shows pinned customer metafields, and both pinned and unpinned product metafields.
• Shopify Flow: workflows can use metafield values in conditions and change them with actions such as Update product metafield or Update customer metafield, per Shopify's Flow metafields guide.

How do metafields differ from metaobjects and category metafields?

Shopify's category metafields guide adds that editing a category metafield entry, such as renaming black to graphite, updates it everywhere that entry is used.

Why isn't a metafield showing? Common pitfalls and fixes

Deleting deserves the most care. Shopify's deleting metafields guide says deletion is permanent, offers Delete field only to keep the saved values, and warns that deleting a metafield used by your live theme can break the storefront.

Once metafields drive what customers see, check them on a schedule. Our Shopify metafield audit checklist covers blank values, mismatched definitions and storefront gaps, and our size chart guide shows one common metafield setup end to end. ShopOpsy is also building Metafield Error Scanner, an app to scan a catalog for missing, empty or invalid metafield values; it isn't available yet.

Frequently asked questions

Do Shopify metafields cost extra?

No. Shopify lists metafields and metaobjects as a built-in feature "Included with Shopify". Apps can add other editors or sync tools, but definitions, values and dynamic sources work without one.

Can I change a metafield's type later?

Not directly. Type isn't among the editable parts of a custom definition. Shopify's deleting guide describes the route that remains: delete the definition with Delete field only, which keeps the values, then migrate them to a new custom definition with the same namespace and key. Values that don't match the new definition need fixing, so export a backup and test on one product first.

Sources

• Metafields — Shopify Help Center, accessed 26 October 2026.
• Overview of custom data — Shopify Help Center, accessed 26 October 2026.
• Adding metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Parts of a metafield definition — Shopify Help Center, accessed 26 October 2026.
• Metafield content types and values — Shopify Help Center, accessed 26 October 2026.
• Adding standard metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Creating custom metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Migrating metafields to a definition — Shopify Help Center, accessed 26 October 2026.
• Editing custom metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Options for custom data — Shopify Help Center, accessed 26 October 2026.
• Adding values to metafields — Shopify Help Center, accessed 26 October 2026.
• Pinning metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Editing metafields in bulk — Shopify Help Center, accessed 26 October 2026.
• Using CSV files to import and export products — Shopify Help Center, accessed 26 October 2026.
• Displaying metafields on your online store — Shopify Help Center, accessed 26 October 2026.
• Sections and blocks — Shopify Help Center, accessed 26 October 2026.
• Search & Discovery filters — Shopify Help Center, accessed 26 October 2026.
• Shopify Search & Discovery — Shopify App Store, accessed 26 October 2026.
• Collections with metafields — Shopify Help Center, accessed 26 October 2026.
• Filtering products using product metafields — Shopify Help Center, accessed 26 October 2026.
• Metafield segment filters — Shopify Help Center, accessed 26 October 2026.
• Category metafields — Shopify Help Center, accessed 26 October 2026.
• Variants — Shopify Help Center, accessed 26 October 2026.
• Metafields in Shopify Flow — Shopify Help Center, accessed 26 October 2026.
• Deleting metafields — Shopify Help Center, accessed 26 October 2026.
• Fixing metafield validation errors — Shopify Help Center, accessed 26 October 2026.
• Metafields and metaobjects (built-in feature) — Shopify App Store, accessed 26 October 2026.
• About custom data — Shopify developer documentation, accessed 26 October 2026.
• Metafield limits — Shopify developer documentation, accessed 26 October 2026.
• MetafieldOwnerType — Shopify developer documentation, accessed 26 October 2026.
• Dynamic sources — Shopify developer documentation, accessed 26 October 2026.
• Liquid metafield object — Shopify developer documentation, accessed 26 October 2026.
• Liquid metafield_tag filter — Shopify developer documentation, accessed 26 October 2026.
• Market metafields available as a dynamic source in the Online Store editor — Shopify Changelog, accessed 26 October 2026.
• Smart collections now support metaobject reference metafields — Shopify Changelog, accessed 26 October 2026.