Shopify Metaobjects Explained: When to Use Them Instead of Metafields

Shopify metaobjects are content types you design yourself: a set of fields, such as a designer's name, photo and bio, with one entry per item, managed in Shopify admin under Content > Metaobjects. A metafield adds one field to a record that already exists, like a product. A metaobject is a separate record that many products, collections or pages can point to through a metaobject reference metafield.

Use a metaobject when the same group of details repeats across products (a designer, an ingredient, a size chart, an FAQ) or deserves its own web page. Use a plain metafield for a single value that belongs to one product. Shopify lists metafields and metaobjects as a built-in feature included with Shopify, so no app is needed to start.

Steps below follow Shopify's Help Center and developer documentation as of October 2026. Shopify's help pages call the settings area either Settings > Metafields and metaobjects or Settings > Custom data; use whichever your admin shows, and expect other small label differences.

What are metaobjects in Shopify?

Shopify's metaobjects overview presents them as the option for data that is best represented by several fields: you create an object with multiple fields, then reference it from metafields or show it on its own. Every metaobject has two parts:

• A definition: the structure. It holds a name (such as "Designers"), a type identifier generated from that name, the fields each entry has, a display name field and options that control where the content can be used.
• Entries: the content. Each entry fills in the fields once, such as one entry per designer. You manage entries in Content > Metaobjects.

Shopify's developer data modeling guide puts it in database terms: metafields are like new columns on existing Shopify resources, while metaobjects are like custom tables of your own.

You may already use metaobjects without knowing it. The metaobjects overview says Shopify's product taxonomy uses metaobjects, and each category metafield, such as color or fabric on a shirt, has default entries built with metaobject definitions. That is why you may see them listed in Content > Metaobjects.

Metafields vs metaobjects: what's the difference?

Our guide to Shopify metafields covers the basics. In short:

The two work together: to show a designer on a product page, you add a product metafield of type Metaobject, then pick the designer on each product.

When should you use a metaobject instead of a metafield?

Shopify's developer overview recommends metafields for a single custom value on an existing resource, and metaobjects for structured data with several related fields or data that several resources reference. In practice, choose a metaobject when any of these is true:

• Several fields describe one thing. A designer has a name, a photo and a bio; as product metafields, all three would be retyped on every product.
• Many records share it. Forty products by one designer point to one entry, so a corrected bio fixes all forty.
• It needs its own page. Store locations or designers can each become a web page from one theme template.
• Shoppers should filter by it with swatches or images. Visual filters in Search & Discovery are built on metaobject references.

Stay with a plain metafield when the value is unique to one record, such as a launch date. If a shared thing carries a detail that differs per product, such as an ingredient's amount, keep that detail on the product; the data modeling guide's alternative, a joining metaobject, is harder to query.

What can you use Shopify metaobjects for?

These Shopify metaobject examples are common setups. The field names are suggestions, not Shopify defaults.

Size charts, ingredient lists and author profiles all appear in Shopify's developer overview, and FAQs and influencer profiles in its Help Center. One caution on size charts: dynamic sources fill one theme setting per field, so a full measurement table usually needs a purpose-built section or custom Liquid. Our size chart guide compares this with the no-code page method, and our free size chart generator turns your measurements into an HTML table for that page. For product highlights, Shopify's worked example builds the whole setup step by step.

How do you create a metaobject definition?

These steps follow Shopify's guide to building a metaobject:

1. From your Shopify admin, go to Content > Metaobjects or to the settings area (Settings > Custom data or Settings > Metafields and metaobjects).
2. Click Add definition.
3. In Name, enter a name such as "Designers". Shopify generates the type identifier from it; edit it now if you want, because Shopify's definition management guide says type identifiers can't be changed after creation.
4. Click Add field, enter a Field label such as "Name", click Select field type and choose a type, such as Single line text or File > Image.
5. Optional: click the asterisk beside the field label to make the field required, and use the Validation and Description tabs, where shown, to limit accepted values or describe the field.
6. Add the remaining fields and drag them into order.
7. Review the options described below, then click Save.

The display name is the field that identifies each entry in admin and in drop-downs. Shopify assigns it to the first text field by default, and you can change it later. Pick a field that is unique, such as the designer's name, so staff can tell entries apart.

Which field types can a metaobject use?

Metaobjects use the same data types as metafields, according to Shopify's list of data types. The Help Center's content types reference groups them as text, number, measurement, date and time, references (product, variant, collection, page, article, customer, company, file and metaobject), other types such as true or false, color, URL and money, and advanced types (JSON and mixed reference).

A field can reference another metaobject, so a Designer entry can point to a Country entry. Use real reference fields for links like this; the data modeling guide warns that storing IDs or handles as text breaks the connection.

Which options should you set before saving?

Shopify's options for custom data list these for metaobject definitions:

Depending on your admin version, the web pages option may appear as Web pages under Features. To change options later, open the definition, adjust its Options section and click Save.

How do you add metaobject entries?

Shopify's creating entries guide gives these steps:

1. Go to Content > Metaobjects and click the definition.
2. Click Add entry.
3. Fill in the fields.
4. Optional: set the status. New entries are Active by default; Shopify says Active means ready to display, but not shown to customers until you publish it, and a Draft entry can't be published at all.
5. Optional: if the definition doesn't publish entries as web pages, edit the auto-generated Handle with the pencil icon. For a web page entry, choose a theme template and preview it with the eye icon.
6. Click Save.

To edit an entry, open it from the same list, change the values and save; the change appears everywhere the entry is used. To change which fields entries have, edit the definition instead. The list also has saved views, such as Web pages and Draft, per Shopify's Content section guide.

How do you connect metaobject entries to products?

An entry shows on a product page only after the product points to it. Shopify's referencing guide sets this up in two stages.

Create the reference metafield once:

1. Go to Settings > Metafields and metaobjects and choose the part of the store, such as Products.
2. Click Add definition and enter a name. Reusing the metaobject's name, such as "Designer", keeps things easy to find.
3. Click Select type, choose Metaobject and select your definition. Mixed reference allows more than one metaobject type, with limits covered below.
4. Choose One value for one entry per product, or List of values for several.
5. Keep Storefronts access selected, then click Save.

Pick entries on each product:

1. Open a product and go to its Metafields section. If the field isn't listed, click Show all (Shopify's guide to adding values to metafields calls this button View all).
2. Click the field, then Select entry (or Select entries for a list) and choose from the drop-down.
3. Click Save.

You can also click Create new inside the field to add an entry without leaving the product; the new entry is then available to other products too. Other parts of the store work the same way, such as collections, pages or blog posts, through a metafield definition on that part. For many products, our Shopify bulk editor guide covers editing product metafields as columns; check that your reference field is offered before you plan around it.

How do you show metaobjects in your theme?

Can you show metaobjects without code?

Yes, with dynamic sources in the theme editor. They need a modern theme: Shopify's theme architecture comparison lists them for Online Store 2.0 and theme block themes, not vintage themes. Then, following Shopify's connecting guide:

1. Go to Online Store and click Edit theme.
2. Pick the template from the menu at the top, such as your default product template.
3. Click the block or setting you want to fill.
4. Click the Connect dynamic source icon next to the setting.
5. Choose the source. Under From this template section, click Template > Product and pick a compatible metaobject reference metafield. Under From your store, pick Metaobjects to use one entry directly, without a product reference, which suits content that isn't tied to one product, such as homepage content.
6. Select the field to show, then click Save.

What decides whether it works:

• Field types must match the setting, such as a text field for a heading setting.
• Storefronts access must be on for the metaobject.
• Lists are filled automatically: if the field is a list, the theme editor adds each entry in the list to the block setting.
• Products without an entry can show a gap. Shopify's worked example suggests a separate product template for products that have entries.

Since a December 2024 update, metaobject fields can be used on any relevant section or block in the theme editor without code. Shopify's web pages guide adds that for image, video, color, product, page, collection and text fields you can edit the entry straight from the theme editor: click the entry in the sidebar, then Edit value. Only the entry currently previewed can be edited this way.

How do developers show metaobjects with Liquid?

When no block fits, a developer can read entries in theme code. Here custom.designer and custom.highlights stand in for your own reference metafields:

{% assign designer = product.metafields.custom.designer.value %}
{% if designer %}
  <h3>{{ designer.name.value }}</h3>
  <p>{{ designer.bio.value }}</p>
{% endif %}

{% for highlight in product.metafields.custom.highlights.value %}
  <p>{{ highlight.heading.value }}: {{ highlight.caption.value }}</p>
{% endfor %}

Shopify's Liquid metaobject reference adds metaobjects.type.handle for entries not attached to a product, and notes that, with Active-draft status on, a draft entry returns nil, so nothing renders. Duplicate your theme before editing code.

How do Shopify metaobject pages and templates work?

Turning on web pages gives every entry a URL and renders it with one theme template. Shopify's web pages guide splits it into three steps.

1. Activate web pages on the definition:

1. Go to Settings > Metafields and metaobjects and click the metaobject.
2. In Options, make sure Storefronts access is on, then select Publish entries as web pages.
3. Choose which fields supply the page title and meta description for search engines. Enable in Online Store is selected by default; deselect it only for a Hydrogen storefront.
4. Optionally customize the URL handle, then click Save.

2. Create entries as described above.

3. Build the metaobject template:

1. Go to Online Store and click Edit theme.
2. Open the page selector at the top, click Create metaobject template and choose the metaobject.
3. Review the page title, meta description and URL handle in Search engine listing, then click Create template.
4. Add sections and blocks, connect them to the entry's fields with dynamic sources, and click Save.

If you skip step 1, creating the template turns web pages on anyway. Per Shopify's metaobject template docs, the first template becomes the default for all active entries.

Where the pages live: Shopify's capabilities guide shows a URL handle of content giving entry URLs of /pages/content/{entry-handle}. So a "stores" URL handle and a "london" entry would live at /pages/stores/london. The same guide says metaobjects with the renderable capability, which supplies the SEO title and description, are included in the store's sitemap. The Help Center doesn't state this for pages set up in admin, so check your sitemap after publishing.

To send shoppers there, Shopify suggests linking to the page from a homepage section or adding the link to a menu, which you edit in Content > Menus per Shopify's menus guide. Because the entry's handle is part of the URL, settle handles before you share links.

Can metaobjects power filters, collections and reports?

Metaobject references also power merchandising features:

• Storefront filters with swatches. Shopify's Search & Discovery filters guide builds visual filters from a product or variant metafield that references a metaobject. The metaobject needs a color field or an image field (one value each) and a field that names the filter value, and both definitions need Storefronts access. Your theme must support the filter value API, and a filter shows up to 100 values.
• Smart collections. Since December 2024, metaobject reference metafields are available as smart collection conditions, so "all products by this designer" can update itself.
• Reports. With Filter or group data in Analytics on, metaobject fields can filter or group reports, as long as a product, variant, customer or order metafield references the metaobject. Mixed references can't be used this way.

Can you translate metaobject entries?

Turn on Translations in the definition's options; Shopify's options guide says this lets entries be translated into other languages. For developers, the capabilities guide shows translations being registered for metaobject fields through Shopify's translation APIs. Shopify's Help Center doesn't list which translation apps show metaobject entries, so if you use one, such as Shopify's Translate & Adapt, open a few entries in it to confirm they appear before you launch a new language.

What are the Shopify metaobject limits?

From Shopify's metaobject limits page:

Standard metaobject definitions and their entries don't count toward the definition and entry limits. In practice, the Liquid limits bite first: a theme that loops over a long list without pagination stops at 50 entries.

Why isn't a metaobject showing up? Common pitfalls

Two actions deserve extra care:

• Deleting an entry can't be undone, and Shopify says it is removed from everywhere it is published or used.
• Deleting a definition goes further. Shopify's API reference for deleting a metaobject definition says it also deletes the related metafield definitions, entries and metafields. Export what you need first, and check which products reference it.

Also plan field types before you add hundreds of entries: Shopify's docs don't describe changing an existing field's type, and its worked example advises against editing a handle once the entry is in use.

Reference metafields can look filled while pointing to an outdated entry, so include them in reviews with our Shopify metafield audit checklist. If validation rules flag saved values, our guide to fixing metafield validation errors covers the cleanup. 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

Can I import metaobject entries from a CSV file?

Shopify's metaobject help pages describe creating entries one at a time in admin and don't describe a CSV import. For hundreds of entries, developers can use the GraphQL Admin API, or you can use a bulk-editing app from the Shopify App Store. Test on a few entries first.

Can metaobjects replace product variants?

Not for options a shopper picks before buying, such as size or color, because variants carry their own price, SKU and inventory. Metaobjects suit descriptive information shared across products. Our guide to the Shopify variant limit covers when moving descriptive data out of options makes sense.

Sources

• Metaobjects — Shopify Help Center, accessed 26 October 2026.
• Building a metaobject — Shopify Help Center, accessed 26 October 2026.
• Creating entries — Shopify Help Center, accessed 26 October 2026.
• Referencing metaobjects — Shopify Help Center, accessed 26 October 2026.
• Adding values to metafields — Shopify Help Center, accessed 26 October 2026.
• Connecting and displaying metaobjects — Shopify Help Center, accessed 26 October 2026.
• Creating and connecting a metaobject — Shopify Help Center, accessed 26 October 2026.
• Building web pages with metaobjects — Shopify Help Center, accessed 26 October 2026.
• Options for custom data — Shopify Help Center, accessed 26 October 2026.
• Navigating the Content section in the admin — Shopify Help Center, accessed 26 October 2026.
• Metafield content types and values — Shopify Help Center, accessed 26 October 2026.
• Search & Discovery filters — Shopify Help Center, accessed 26 October 2026.
• Theme architecture versions — Shopify Help Center, accessed 26 October 2026.
• Editing menus — Shopify Help Center, accessed 26 October 2026.
• About metaobjects — Shopify developer documentation, accessed 26 October 2026.
• Data modeling with metafields and metaobjects — Shopify developer documentation, accessed 26 October 2026.
• Use metaobject capabilities — Shopify developer documentation, accessed 26 October 2026.
• Manage metaobject definitions — Shopify developer documentation, accessed 26 October 2026.
• Metaobject limits — Shopify developer documentation, accessed 26 October 2026.
• List of data types — Shopify developer documentation, accessed 26 October 2026.
• Metaobject templates — Shopify developer documentation, accessed 26 October 2026.
• Liquid metaobject object — Shopify developer documentation, accessed 26 October 2026.
• metaobjectDefinitionDelete — Shopify developer documentation, accessed 26 October 2026.
• Metaobjects available everywhere in online store editor — Shopify Changelog, accessed 26 October 2026.
• Smart collections now support metaobject reference metafields — Shopify Changelog, accessed 26 October 2026.
• Metafields and metaobjects (built-in feature) — Shopify App Store, accessed 26 October 2026.