Ecom Store Pro

How to Use Metaobjects in Shopify: Definition to Storefront

Create a metaobject definition, add entries, link them to products and show them in Horizon with dynamic sources, plus what deleting one breaks.

Listen to a short brief of this article
Hands-free while you multitask

The short version

To use a metaobject, create its definition in Settings › Metafields and metaobjects, add entries in Content › Metaobjects, and connect its fields to a theme block with Connect dynamic source.

Content that differs from product to product also needs a product metafield of type Metaobject, set to One entry or List of entries, with the entry picked on each product.

Keep storefront access on, or nothing reaches your online store.

Deleting a definition can't be undone, deletes all of its entries and can cause display errors if your live theme still uses it.

How a Metaobject Gets From Your Admin to Your Storefront

Key takeaway

A metafield stores one value on one record, such as a product. A metaobject is a set of fields you fill in once as an entry and reuse wherever you need it, so if you are still deciding between the two, start with how a metafield and a metaobject compare.

Shopify's Help Center uses examples such as a product highlight, an influencer profile, an FAQ and an event appearance. For an FAQ, you include fields for a question and an answer, create an entry for each question and display them in a section of your theme. A size chart is another common case, and our size chart guide walks through that build.

Every metaobject has two parts in two places. The definition is its structure, the group of fields, and the entries are the content you fill in. Between them and your storefront sit up to three more steps:

1
Create the definition
Name it and add its fields in Settings › Metafields and metaobjects. Content › Metaobjects has an Add definition button too.
2
Add entries
Fill in one entry per item in Content › Metaobjects.
3
Add a reference metafield
Only for content that differs per product: a product metafield of type Metaobject points at your entries.
4
Pick entries on each product
In the product's Product metafields card, choose the entry that product shows.
5
Connect it in the theme editor
Use Connect dynamic source on a block setting in Horizon to show the entry's fields.

If you prefer to watch the whole chain first, this tutorial from the independent channel Sunrise Integration creates a metaobject, adds entries, assigns it to a metafield and connects it to a theme. It was uploaded in March 2023, so some screen names may differ from today's. In our test admin in November 2026, the settings page was Metafields and metaobjects, and the reference menu read One entry or List of entries. Take the names from the steps below.

Creating and Using Shopify Metaobjects - Shopify TutorialCreating a metaobject, adding entries, assigning it to a metafield and showing it in a theme, from the independent channel Sunrise Integration, March 2023. Some screen names may differ from today's; take current names from this page.

Do You Need a Reference Metafield?

Key takeaway

Where the entries should appear decides which steps you need. The definition and its entries come first on every route; find your row before you build the rest.

Which route fits your content
Where entries should appearReference metafield?How it reaches the page
On product pages, different for each productYes: One entry or List of entriesPick entries on each product, then connect a product template block with Connect dynamic source
On product pages, the same for every productNoConnect dynamic source on the product template, then From your store and Metaobjects, if your block offers that option
On the home page, the same for every visitorNoConnect dynamic source, then From your store and Metaobjects
Each entry as its own pageNoThe Web pages feature and a metaobject template
Several metaobject types in one fieldYes: Mixed referenceLiquid or the Storefront API only, not the theme editor

Create the Metaobject Definition

Key takeaway

Check the prebuilt definitions first: Shopify's guidance is to create a custom metaobject when no standard definition meets your needs. The example below is a custom Product highlights definition with two fields.

  1. From your Shopify admin, go to Settings › Metafields and metaobjects. Content › Metaobjects has an Add definition button too.
  2. Click Add definition.
  3. Enter a Name, for example Product highlights. The type identifier, product_highlights here, is generated from the name and appears under it.
  4. Click Add field, enter a label, then click Select field type and search for or select the type, for example Single line text for a title.
  5. Repeat for each field. Under Field options, Display name sets the field that identifies each entry; you can change it at any time.
  6. Set the Metaobject options described below, then click Save.
In Shopify adminOpen in your store
  1. Settings
  2. Metafields and metaobjects
  3. Add definition
Name the definition, then add each field with its type; the type identifier appears under the name.
Settle the type identifier before you save

Shopify's Help Center says you can edit the type identifier before saving. Shopify's developer documentation goes further: type identifiers can't be changed after creation. Treat it as permanent.

You can also create a definition straight from a reference field on a resource page, such as a product, without going to Settings.

Match field types to the theme block you will use

Key takeaway

You pick a type from a searchable list of categories and presets, such as text, file or URL. Shopify's own example is a Single line text field connected to the Heading or Caption setting of a Column block.

  • A title or short label: Single line text.
  • A paragraph of copy: Multi-line text, like the Description field in the example.
  • A picture: File, then Image.

Which options to turn on

Key takeaway

The Metaobject options block sits under the fields. A new definition opens with the settings below, and you can edit these options at any time.

Metaobject options, as a new definition opens
OptionNew definitionWhat it doesKeep it on when
Storefronts API accessOnLets your online store display the entries; Shopify says a metaobject needs storefront access for thatShoppers should see the entries
Active-draft statusOnEntries can move between active and draft; a Draft entry can't be publishedYou want to prepare entries before they go live
TranslationsOnEntries can be translated into different languagesYou sell in more than one language
Publish entries as web pagesOffLets you build a theme template that gives each entry its own page; needs storefront accessEntries need their own pages (it also switches on by itself when you create a metaobject template)
Filter or group data in AnalyticsOffMakes the fields usable in Analytics reports once a product, variant, customer or order metafield references the metaobjectYou want reports grouped or filtered by these fields
Customer Account API accessOffNo step in this guide uses itNot needed for anything on this page
In Shopify adminOpen in your store
  1. Settings
  2. Metafields and metaobjects
  3. Add definition
Storefront access, draft status and translations start on; web pages and Analytics start off.

Since September 28, 2026, fields of a metaobject attached to a product, variant, customer or order through a metafield can be used in Analytics, and Filter or group data in Analytics is where you turn a definition on or off. Which fields work in reports is a question of its own.

Add Entries

Key takeaway
  1. From your Shopify admin, go to Content › Metaobjects.
  2. Click the definition you want to add entries to, for example Product highlights.
  3. Click Add entry.
  4. Fill in the fields. The Handle on the right is generated automatically; in our test the handle came from the Title field.
  5. Optional: set the Status. New entries are Active by default.
  6. Click Save.
In Shopify adminOpen in your store
  1. Content
  2. Metaobjects
  3. Product highlights
  4. Add entry
Steps 4 and 5: Handle and Status sit on the right; here the handle came from the Title.

Active doesn't mean live. In Shopify's words, Active means the entry is ready to be displayed in your store, but it won't be displayed to customers until you publish it. An entry set to Draft can't be published at all. In practice, an Active entry shows once you connect it to a block or a template, which the next sections walk through.

Leave the handle alone once the entry is in use: editing it then affects references set manually in your store, including in Liquid, and can leave a product without its entry.

Once an entry is published, edits to its content show automatically wherever it is used. To change the fields an entry uses, edit the definition, not the entry. If you have dozens of entries to load, whether you can bulk import them is answered separately.

Connect Entries to Products With a Reference Metafield

Key takeaway

Entries on their own aren't tied to any product. To use a metaobject in a specific part of Shopify, such as products, orders or customers, you create a metafield reference.

  1. Go to Settings › Metafields and metaobjects.
  2. In the Metafields section, click Products, then Add definition.
  3. Enter a name, for example Product highlights.
  4. Click Select type, search for or select Metaobject, then pick your definition.
  5. Choose One entry or List of entries. Shopify's Help Center calls these One value and List of values.
  6. Keep Storefront API access on, then click Save.
In Shopify adminOpen in your store
  1. Settings
  2. Metafields and metaobjects
  3. Products
  4. Add definition
Step 5: the menu beside the Metaobject type sets One entry or List of entries.

The same type list also offers Mixed reference, which lets one field point at more than one metaobject type. That flexibility costs you the theme editor:

One entry, a list or a mixed reference
ChoiceUse it whenHow it reaches the storefront
One entryEach product shows a single entryTheme editor: connect a field to a block setting of the same type
List of entriesA product shows more than one entryTheme editor: it adds each entry in the list to the block setting
Mixed referenceOne field must point at more than one metaobject typeLiquid or the Storefront API only; its fields can't be dimensions or filters in your reports
  1. Go to Products and open a product.
  2. In the Product metafields card, click Add in the Product highlights row.
  3. Choose an entry under Search entries, or click Add entry to create one. Shopify's Help Center calls that button Create new.
  4. Click Save.
In Shopify adminOpen in your store
  1. Products
  2. Product metafields
Step 3: pick an existing entry, or create one with Add entry.

Show Metaobjects in Horizon With Dynamic Sources

Key takeaway

Shopify documents three ways to show a metaobject from the theme editor: connect the metaobject to a block, connect its fields to block or theme settings with dynamic sources, or edit the theme code. Since December 11, 2024, Shopify says metaobject fields work on any relevant section or block without custom code, in themes whose blocks support dynamic sources. The steps below use a product template in Horizon.

  1. From your Shopify admin, go to Online Store › Themes and click Edit theme.
  2. In the page selector at the top, open the template, for example Default product.
  3. Select a block, for example Description inside Product information.
  4. Beside the setting, for example Text, click Connect dynamic source.
  5. Click Product, then Product highlights, and choose the field.
  6. Click Save.
In Shopify adminOpen in your store
  1. Online Store
  2. Themes
  3. Edit theme
Steps 4 and 5: the database icon beside Text opens the picker, shown here on Product highlights and its fields.

Only metaobjects and metaobject references connect to a block, and only fields whose type matches the setting connect to it.

With a List of entries field, the theme editor automatically adds each entry in the list to the block setting. How that renders depends on the block, and our FAQ on reusing answers with a metaobject covers what it looks like in a Horizon FAQ section.

On the home page

Content that is the same for every visitor needs no reference metafield. On the home page you can connect any custom metaobject from Content › Metaobjects directly: click Connect dynamic source, then Metaobjects under From your store. What you can't connect there are metafields that come from a product's metaobject reference.

Products with no entry

In Shopify's Product highlights tutorial, a product with no assigned entry left the section blank, as whitespace, instead of removing it, and Shopify notes that the exact behavior might vary by theme and section. If that looks wrong on your store, create a separate product template and assign it only to the products that have entries.

When a block has no dynamic source option

Not all sections or blocks support dynamic sources, and support depends on your theme. Try another block that takes the same kind of content. Otherwise the remaining route is the theme code, which Shopify advises editing only if you have coding experience, and a Mixed reference always needs that route. If you hire someone for that work, our guide to Shopify development covers who to hire and typical budgets.

Give Each Entry Its Own Page

Key takeaway

Shopify describes this as using metaobjects to build repeatable landing pages: one template, one page per entry.

  1. In the theme editor, open the page selector at the top.
  2. Click Create metaobject template.
  3. In the dialog, click the definition you want to use, for example Product highlights, then click Create template.
  4. Build the template like any other, then click Save.
In Shopify adminOpen in your store
  1. Online Store
  2. Themes
  3. Edit theme
Step 3: the dialog lists your definitions; pick the one whose entries get pages.

If you don't switch the Web pages feature on in the definition yourself, creating a metaobject template from the theme editor switches it on for you. To do it by hand, select Publish entries as web pages in the definition's options and make sure storefront access is on.

Each entry's Page title and Meta description come from fields you choose, and you can edit the URL handle in the Search engine listing section. Enable in Online Store is selected by default; if you run a Hydrogen storefront, deselect it.

Shopify announced this capability in its Summer '23 Edition. The short official clip below shows the idea rather than today's clicks.

Custom landing pages powered by Metaobjects announced in Shopify's Summer '23 EditionShopify's official Summer '23 Edition announcement of custom landing pages built from metaobjects, July 2023. An overview of the idea; take the current steps from this page.

Why Doesn't My Metaobject Entry Show Up?

Key takeaway

Work down the table in order; the first rows are the quickest to check. The saved views at the top of Content › Metaobjects, starting with Available on storefront, are a fast first look.

In Shopify adminOpen in your store
  1. Content
  2. Metaobjects
Start with Available on storefront, the first saved view above the definitions.
An entry that doesn't show: causes in checking order
What's wrongWhere to checkFix
Storefronts API access is off on the definitionThe definition's Metaobject optionsTurn it on; without storefront access the metaobject can't display on your online store
The entry is DraftThe entry's StatusSet it to Active; a Draft entry can't be published
The entry is Active but connected nowhereThe theme editorActive means ready to display, not displayed: connect it to a block or a template
The product has no entry selectedThe product's Product metafields cardAdd the entry; a section with no entry can be left blank
Storefront API access is off on the reference metafieldSettings › Metafields and metaobjects › Products › your fieldTurn it on so the storefront can read the field
The field type doesn't match the block settingThe definition's fields and the block's settingsUse a field whose type matches the content the setting takes
The block doesn't support dynamic sourcesThe theme editor, beside the settingUse another block that takes the same content, or theme code
The field is a Mixed referenceThe reference metafield's typeThe theme editor can't connect it; it needs Liquid or the Storefront API

What You Can't Undo

Key takeaway

Two deletions are permanent. Before you delete a definition, Shopify asks you to check your live theme:

Before you delete a metaobject, make sure that it isn't connected to a block or section in your live theme. Deleting metaobjects that are connected to your theme can cause display errors for customers visiting your online store.
Shopify — Building a metaobject — Shopify Help Center ·

Skipping that check also blocks your own work: you need to resolve those errors before you can make any other changes to the theme templates associated with that metaobject.

Changes to plan before you make them
ActionWhat happensBefore you do it
Delete a definitionCan't be undone; every entry of that metaobject is deleted tooDisconnect it from every block and section in your live theme
Delete an entryCan't be undone; it's removed from everywhere it's published or usedCheck which products, pages and blocks use it
Edit an entry's handleIf the entry is already in use, the edit affects references set manually in your store, including in Liquid, and can leave a product without its entrySettle the handle before the entry is used anywhere
Change the type identifierEditable before you first save; Shopify's developer documentation says it can't change after creationCheck it under the name before you click Save

Limits to know before you build

Key takeaway

The first three limits come from Shopify's developer documentation, read on November 14, 2026, and standard definitions don't count toward the definitions limit. The developer documentation's plan names are Basic, Shopify, Advanced, Plus and Enterprise; Shopify's pricing page, read the same day, lists Basic, Grow, Advanced and Plus.

In themes that support dynamic sources, the ceiling of 100 applies to each template and to each section group. Each static section can have up to 50 dynamic sources in total. If your theme supports dynamic sources in theme settings, then your theme settings can have up to 100 dynamic sources in total.

40
Fields per definition
128 / 256
Definitions: Basic, Shopify, Advanced / Plus, Enterprise
1,000,000
Entries per definition
100
Dynamic sources per template, in themes that support them

Sources: Metaobject limits — Shopify.dev · Sections and blocks — Shopify Help Center

Metaobject Setup Checklist

Key takeaway

Steps 1 to 3 apply to every route. Skip steps 4 and 5 for content that is the same on every product, for home page content and for entries that get their own pages; for those, step 6 happens on the product template, on the home page or in the metaobject template, and step 7 is a check of the storefront page that shows the connected block or template.

Metaobject setup, from definition to storefrontTick each step off as you go; your progress stays in this browser.

Metaobject setup, from definition to storefront

Tick each step off as you go; your progress stays in this browser.

0 of 7 done
  1. Add a definition in Settings › Metafields and metaobjects with the fields your theme blocks need.

  2. Keep Storefronts API access on, leave Translations on if you sell in more than one language, and switch on other options only if you need them.

  3. Create one entry per item in Content › Metaobjects and leave it Active.

  4. For per-product content, add a product metafield of type Metaobject with One entry or List of entries.

  5. Select the entry in each product's Product metafields card and save.

  6. In the theme editor, connect each block setting to its field with Connect dynamic source, then save.

  7. Open a product with an entry and one without, and confirm both look right.

The Bottom Line

Key takeaway

Every step happens in the admin and the theme editor, and none of it needs code unless you choose a Mixed reference or your block has no dynamic source option.

Build one definition end to end on one product before you fill in the catalog. Every cause in the troubleshooting table shows up on that first product, and fixing it there is cheaper than fixing it across the catalog.
Your Next Step by Stage
Want shoppers to filter by itSee how Search & Discovery turns metafields, including metaobject references, into storefront filters.Search & Discovery guide
Not on Horizon yetIf your current theme's blocks can't connect metaobject fields, see what moving to Horizon involves.Horizon theme guide
Ongoing theme workA monthly block of developer hours covers continuing theme customization, including new sections built on your metaobjects.See developer services

Need a Metaobject Section the Theme Editor Can't Build?

Theme code work at $28 an hour: a custom section that renders a Mixed reference, which only Liquid or the Storefront API can display, or a list of entries the way you want. Your definitions and entries stay in your admin.

Get a Shopify developer

Frequently Asked Questions

Not for the standard route. The definition, the entries, the reference metafield and the theme editor connection are all set up in your Shopify admin without code. You need theme code only for a Mixed reference, which reaches the storefront through Liquid or the Storefront API, or for a block with no dynamic source option. Shopify advises editing theme code only with coding experience.
Definitions live in Settings › Metafields and metaobjects, which some Shopify Help Center pages call Custom data. Content › Metaobjects also has an Add definition button, and it is where you add and edit entries. Reference metafields that tie entries to products are created in Settings › Metafields and metaobjects, under Products.
Field changes go through the definition, not the entry: Shopify says that to change the fields an entry uses, you edit the metaobject definition. Editing an entry's content is different: once the entry is published, your edits show automatically wherever it is used, though editing an in-use entry's handle can break references. Plan field types before adding entries: each must match a theme block setting.
Deleting a metaobject definition can't be undone, and every entry of that metaobject is deleted with it. If the metaobject is connected to a block or section in your live theme, customers can see display errors, and you must resolve them before making other changes to the theme templates that use it. Disconnect it from the theme first.
The entry is removed from everywhere it is published or used in your store, and Shopify says deleting an entry can't be undone. Before you delete one, check which products reference it in their Product metafields card and which theme blocks or pages show it, so a product page doesn't lose content you meant to keep.
Shopify's Help Center says the type identifier is generated from the name and that you can edit it before saving. Shopify's developer documentation adds that type identifiers can't be changed after creation. Treat it as permanent: check the identifier shown under the name, such as product_highlights, before you click Save for the first time.
Usually one link in the chain is missing. Check that Storefronts API access is on for the definition, the entry is Active rather than Draft, the product has the entry selected, the reference metafield has Storefront API access on, the field type matches the block setting, and the block supports dynamic sources. Active alone means ready to display, not displayed.
No. On the home page you can connect any custom metaobject from Content › Metaobjects directly: in the theme editor, click Connect dynamic source, then Metaobjects under From your store. What you can't connect there are metafields that come from a product's metaobject reference. A reference metafield is for content that differs from product to product.
Choose One entry if each product shows a single entry, and List of entries if a product shows several. With a list, the theme editor adds each entry in the list to the block setting you connect, so check how your block renders it on a test product. Shopify's Help Center calls the two choices One value and List of values.
No. Shopify says a mixed reference can only be connected to your storefront through Liquid or through the Storefront API for custom storefronts and Hydrogen. Its metaobject fields also can't be used as dimensions or filters in your Shopify reports. If you want a no-code setup, give each metaobject type its own reference metafield instead of mixing them.
Shopify's developer documentation, read on November 14, 2026, lists 128 metaobject definitions on the Basic, Shopify and Advanced plans and 256 on Plus and Enterprise. Standard definitions don't count toward that limit. The same page allows up to 40 fields per definition and up to 1,000,000 entries per definition, and the limits page is the place to recheck these before a large build.
About This Article
Shopify Developer & Editorial Director
9+ years with Shopify since 2017

Front-end developer specializing in Shopify since 2017. Experienced in building custom Liquid themes, optimizing storefront performance, and integrating third-party apps. Directs the editorial process behind Ecom Store Pro: sets its topics and the rules every AI-written page must pass before publication.

Some links in this article are affiliate links. If you sign up for a Shopify store through these links, we may earn a commission at no extra cost to you. Read our full advertising policy.

Continue Learning

What to Read Next

Stay updated

Get notified about new articles

Subscribe to receive updates when we publish new Shopify guides and insights.