Shopify Metaobjects: What They Are and How to Use Them

Who it is for

Store owners and theme developers

Time needed

About an hour for the first metaobject

What you need

Admin access and an Online Store 2.0 theme

A store selling 200 jackets usually has five size charts. Before metaobjects, that meant pasting a chart into 200 product descriptions, then editing 40 of them by hand when a measurement changed. With a metaobject, you create each chart once, link it to the right products, and change it in one place. That's the whole idea, and once a store owner sees it, they start finding uses everywhere.

I use metaobjects on most builds now, for size guides, ingredient lists, designer pages, store locations and FAQs. This guide explains what they are, how they differ from metafields, and the exact steps to create one, connect it and show it in a theme. Admin paths and limits were checked on the Shopify Help Center and shopify.dev on 7 November 2026.

What are Shopify metaobjects?

A metaobject is a structured piece of content with several fields, which you design yourself. It has two parts:

• The definition is the template. It has a name, a type (an identifier Shopify generates from the name, such as size_chart), and a list of fields, each with a type such as single line text, rich text, image, number, color, product reference or a list of values. You can add validation, such as a character limit or preset choices.
• Entries are the content. Each entry fills in the definition's fields: "Men's jackets chart", "Women's jackets chart" and so on.

Each definition has a display name field, which is how entries are labeled in the admin. Shopify uses metaobjects itself: the category metafields that come with Shopify's standard product taxonomy are powered by them.

Shopify metafields and metaobjects: the difference

They work together. You create the metaobject (the size chart), then add a product metafield whose type is a metaobject reference, and pick the right chart on each product. My rule of thumb: if the same content appears on more than a handful of products, or it has more than two fields, it's a metaobject.

Shopify metaobjects examples

These are the uses I set up most often:

• Size charts. Fields: title, table (rich text or JSON), image, fit notes. Linked from a product metafield.
• Ingredients or materials. Fields: name, image, description, benefits. A list of references on each product shows its ingredients, and each ingredient can have its own page.
• Designers, makers or brands. Fields: name, portrait, bio, links. Published as web pages and linked from every product they made.
• Store locations. Fields: address, hours, phone, map link, photo. Shown on a stores page and in the footer.
• FAQs. Fields: question, answer, topic. Pulled into product pages by topic, so a shipping answer is written once.
• Testimonials. Fields: quote, name, product reference, photo. Looped in a homepage section.

How to create a metaobject definition

Here's the size chart example, step by step:

1. Open custom data. In your admin, go to Settings > Custom data, or Content > Metaobjects, and click Add definition. Some older Help Center pages call this area Metafields and metaobjects.
2. Name it. Enter "Size chart". Shopify generates the type size_chart, which you can edit before saving. Pick a clear name, because your theme and any apps refer to this type.
3. Add fields. Click Add field, enter a label, then Select field type. For a size chart: Title (single line text), Chart (rich text), Image (file), Notes (multi-line text).
4. Set rules. Click the asterisk next to a field to make it required. Expand a field to add validation or a description for your team.
5. Check access. Under Access, keep Storefronts selected if the content will appear on your store. Without it, your theme can't read the entries.
6. Choose features. Under Features, select Web pages only if each entry should have its own URL. Size charts don't need it. Designer profiles do.
7. Save. Click Save.

Add entries and connect them to products

1. Add entries. Go to Content > Metaobjects, open Size chart and add an entry for each chart.
2. Create the product metafield. Go to Settings > Custom data, choose Products and add a metafield definition. Name it "Size chart" and pick the Metaobject type, then select the Size chart definition. Use a list type if a product can have several, such as ingredients.
3. Assign charts. Open each product, scroll to the metafields section and pick the right chart. For many products, bulk edit is faster.
4. Show it in the theme. In the theme editor, add a block to the product template, such as a collapsible row or a popup, and use the dynamic source button to connect it to the metafield's fields. Not every section supports dynamic sources, so check your theme.

Product data structure is a big part of a clean catalog. My guide on adding products the right way covers the product fields and metafields to plan before you import.

Publish metaobject entries as web pages

With the Web pages feature, each entry gets its own page, which is how you build designer, ingredient or location pages without an app.

1. Turn it on. Open the definition, make sure Storefronts access is on, and select Publish entries as web pages. Choose which fields become the page title and meta description, and optionally set the URL handle. Leave Enable in Online Store selected unless you use Hydrogen. Save.
2. Create the template. Go to Online Store > Themes and click Edit theme. Open the page selector at the top, click Create metaobject template and choose your metaobject. Check the SEO fields in Search engine listing, then click Create template.
3. Design it. Add sections and blocks and connect them to fields with dynamic sources. Save.
4. Link to the pages. Add them to a menu or link them from products. Pages nobody links to are hard for shoppers and search engines to find.

Using metaobjects in Liquid

Developers can read metaobjects directly in theme code. Through a product metafield that references a size chart:

{% assign chart = product.metafields.custom.size_chart.value %}
{% if chart %}
  <h3>{{ chart.title.value }}</h3>
  {{ chart.chart | metafield_tag }}
{% endif %}

Or looping over every entry of a definition, such as testimonials:

{% for testimonial in metaobjects.testimonials.values %}
  {{ testimonial.author.value }}
{% endfor %}

Watch the rendering limits. A loop without paginate returns 50 entries, paginate allows 250 per page, and looking up entries by handle (metaobjects.TYPE[handle]) is limited to 20 unique handles per type on a page. If the publishable capability is on, loops skip entries in draft.

Shopify metaobject limits

Metaobjects for app developers

Apps can own metaobject types. An app-owned type uses the $app prefix, such as $app:author, and can be declared in shopify.app.toml under [metaobjects.app.author], then released with shopify app deploy. Merchant-owned definitions are created with the metaobjectDefinitionCreate mutation, and entries with metaobjectCreate. Storefront access is off by default for app-owned types and set with access.storefront = "public_read".

One detail matters for checkout logic: Shopify Functions can query app-owned $app metaobjects in their input, but not merchant-owned ones. If you plan a custom app whose function reads configuration from a metaobject, make the app own the type.

Common metaobject mistakes

1. Turning off Storefronts access and then wondering why the theme shows nothing.
2. Using a metaobject for one-off content. If it only appears once, a section setting or a single metafield is simpler.
3. Putting a whole table in an image. Shoppers can't search it, screen readers can't read it, and chatbots can't quote it.
4. Naming types badly. new_thing_2 is hard to maintain. Use clear, singular names.
5. Publishing thin web pages. Each entry page needs real content.
6. Hitting handle lookup limits by fetching many entries by handle on one page instead of using a list reference.

Metaobjects checklist

Next steps

Look through your product descriptions for content that repeats: charts, care instructions, ingredient notes, shipping text. Pick the one that changes most often and turn it into your first metaobject. Once it's linked and showing, the next one takes minutes.

If you'd like help structuring your catalog data or building the theme sections that display it, my Shopify development service starts from $300. Send me a product page and I'll suggest which content belongs in metaobjects.

Frequently asked questions

Sources

1. Metaobjects, Shopify Help Center
2. Building a metaobject, Shopify Help Center
3. Creating web pages with metaobjects, Shopify Help Center
4. Metaobject limits, Shopify.dev
5. About metaobjects, Shopify.dev
6. Liquid object: metaobject_definition, Shopify.dev

Related services and work

Written by Ashraf Siddik

I'm a Shopify developer and CRO specialist. I have built and improved Shopify stores since 2018, completed more than 1,000 projects, and hold a 4.96 average rating across 719 client reviews.

About me · Client reviews