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:
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.
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 appear | Reference metafield? | How it reaches the page |
|---|---|---|
| On product pages, different for each product | Yes: One entry or List of entries | Pick entries on each product, then connect a product template block with Connect dynamic source |
| On product pages, the same for every product | No | Connect 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 visitor | No | Connect dynamic source, then From your store and Metaobjects |
| Each entry as its own page | No | The Web pages feature and a metaobject template |
| Several metaobject types in one field | Yes: Mixed reference | Liquid 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.
- From your Shopify admin, go to Settings › Metafields and metaobjects. Content › Metaobjects has an Add definition button too.
- Click Add definition.
- Enter a Name, for example Product highlights. The type identifier, product_highlights here, is generated from the name and appears under it.
- 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.
- Repeat for each field. Under Field options, Display name sets the field that identifies each entry; you can change it at any time.
- Set the Metaobject options described below, then click Save.
- Settings
- Metafields and metaobjects
- Add definition
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
| Option | New definition | What it does | Keep it on when |
|---|---|---|---|
| Storefronts API access | On | Lets your online store display the entries; Shopify says a metaobject needs storefront access for that | Shoppers should see the entries |
| Active-draft status | On | Entries can move between active and draft; a Draft entry can't be published | You want to prepare entries before they go live |
| Translations | On | Entries can be translated into different languages | You sell in more than one language |
| Publish entries as web pages | Off | Lets you build a theme template that gives each entry its own page; needs storefront access | Entries need their own pages (it also switches on by itself when you create a metaobject template) |
| Filter or group data in Analytics | Off | Makes the fields usable in Analytics reports once a product, variant, customer or order metafield references the metaobject | You want reports grouped or filtered by these fields |
| Customer Account API access | Off | No step in this guide uses it | Not needed for anything on this page |
- Settings
- Metafields and metaobjects
- Add definition
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
- From your Shopify admin, go to Content › Metaobjects.
- Click the definition you want to add entries to, for example Product highlights.
- Click Add entry.
- Fill in the fields. The Handle on the right is generated automatically; in our test the handle came from the Title field.
- Optional: set the Status. New entries are Active by default.
- Click Save.
- Content
- Metaobjects
- Product highlights
- Add entry
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.
- Go to Settings › Metafields and metaobjects.
- In the Metafields section, click Products, then Add definition.
- Enter a name, for example Product highlights.
- Click Select type, search for or select Metaobject, then pick your definition.
- Choose One entry or List of entries. Shopify's Help Center calls these One value and List of values.
- Keep Storefront API access on, then click Save.
- Settings
- Metafields and metaobjects
- Products
- Add definition
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
| Choice | Use it when | How it reaches the storefront |
|---|---|---|
| One entry | Each product shows a single entry | Theme editor: connect a field to a block setting of the same type |
| List of entries | A product shows more than one entry | Theme editor: it adds each entry in the list to the block setting |
| Mixed reference | One field must point at more than one metaobject type | Liquid or the Storefront API only; its fields can't be dimensions or filters in your reports |
Pick the entry on each product
Key takeaway
- Go to Products and open a product.
- In the Product metafields card, click Add in the Product highlights row.
- Choose an entry under Search entries, or click Add entry to create one. Shopify's Help Center calls that button Create new.
- Click Save.
- Products
- Product metafields
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.
- From your Shopify admin, go to Online Store › Themes and click Edit theme.
- In the page selector at the top, open the template, for example Default product.
- Select a block, for example Description inside Product information.
- Beside the setting, for example Text, click Connect dynamic source.
- Click Product, then Product highlights, and choose the field.
- Click Save.
- Online Store
- Themes
- Edit theme
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.
- In the theme editor, open the page selector at the top.
- Click Create metaobject template.
- In the dialog, click the definition you want to use, for example Product highlights, then click Create template.
- Build the template like any other, then click Save.
- Online Store
- Themes
- Edit theme
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.
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.
- Content
- Metaobjects
An entry that doesn't show: causes in checking order
| What's wrong | Where to check | Fix |
|---|---|---|
| Storefronts API access is off on the definition | The definition's Metaobject options | Turn it on; without storefront access the metaobject can't display on your online store |
| The entry is Draft | The entry's Status | Set it to Active; a Draft entry can't be published |
| The entry is Active but connected nowhere | The theme editor | Active means ready to display, not displayed: connect it to a block or a template |
| The product has no entry selected | The product's Product metafields card | Add the entry; a section with no entry can be left blank |
| Storefront API access is off on the reference metafield | Settings › Metafields and metaobjects › Products › your field | Turn it on so the storefront can read the field |
| The field type doesn't match the block setting | The definition's fields and the block's settings | Use a field whose type matches the content the setting takes |
| The block doesn't support dynamic sources | The theme editor, beside the setting | Use another block that takes the same content, or theme code |
| The field is a Mixed reference | The reference metafield's type | The 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.
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
| Action | What happens | Before you do it |
|---|---|---|
| Delete a definition | Can't be undone; every entry of that metaobject is deleted too | Disconnect it from every block and section in your live theme |
| Delete an entry | Can't be undone; it's removed from everywhere it's published or used | Check which products, pages and blocks use it |
| Edit an entry's handle | If 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 entry | Settle the handle before the entry is used anywhere |
| Change the type identifier | Editable before you first save; Shopify's developer documentation says it can't change after creation | Check 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.
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.
Add a definition in Settings › Metafields and metaobjects with the fields your theme blocks need.
Before you tick this off
- Each field's type matches the block setting it will fill
- Type identifier checked before the first save
- Display name points at a field you'll recognise in lists
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.
Before you tick this off
- Storefronts API access is on
- Publish entries as web pages is on only if entries need their own pages
- Translations is on if you sell in more than one language
Create one entry per item in Content › Metaobjects and leave it Active.
Before you tick this off
- Status is Active, not Draft
- Handle settled before the entry is used anywhere
For per-product content, add a product metafield of type Metaobject with One entry or List of entries.
Before you tick this off
- One entry or List of entries chosen, not Mixed reference, unless you will use theme code
- Storefront API access is on
Select the entry in each product's Product metafields card and save.
Before you tick this off
- Every product on the template has an entry, or sits on a separate template
- Each product saved after the entry was picked
In the theme editor, connect each block setting to its field with Connect dynamic source, then save.
Before you tick this off
- The block offers a dynamic source option
- The template is saved
Open a product with an entry and one without, and confirm both look right.
Before you tick this off
- The entry's fields show on the product page
- A product without an entry doesn't leave an unwanted gap
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.
Frequently Asked Questions
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.
This page was written by AI. Separate AI agents that did not write it check its figures and claims against official sources and test its links and interactive tools. A human editor sets the site's editorial direction, topics and rules and checks that pages are complete and display correctly, but does not check their facts or edit their text. Details may change — always confirm critical data at shopify.com.
Editorial PolicySome 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.
