Black Friday to Cyber Monday: 50% off every project over $499. Book before 1 December.

Ends in --d --h --mClaim 50% off

shopify

Shopify Metaobjects: A Step-by-Step Tutorial With Liquid Examples

How Shopify metaobjects work, when to use them instead of metafields, and how to build one: setup, product links, Liquid, web pages and current limits.

Vibhora15 min read

Shopify metaobjects are content types you define yourself, such as a material, a size chart or a designer profile, each with up to 40 fields. You create an entry once and attach it to any number of products, so one edit updates every product that uses it. A metafield adds one field to something Shopify already has. A metaobject creates a new kind of record.

Shopify’s developer docs put the difference in one line each: a metafield is “an extra field on an existing resource”, and a metaobject is “a new record type that you define”. This tutorial builds one from start to finish, a Material type for a clothing store, and shows each place it can appear on the storefront.

The short version:

  1. Define the type under Settings > Custom data > Metaobjects: its name and its fields.
  2. Add entries under Content > Metaobjects, one per material.
  3. Link entries to products with a product metafield whose type is a metaobject reference.
  4. Show them with a dynamic source in the theme editor, in Liquid, or as their own web pages.
  5. Stay inside the limits, the main one being 50 entries per loop in Liquid without pagination.

The definition takes a few minutes in the admin. Most of the work is deciding what deserves its own type.

What is the difference between metafields and metaobjects?

A metafield stores extra data on something Shopify already has, like a product’s care instructions. A metaobject is a separate record with several fields of its own, which you link to products, collections or pages through a metafield. In practice you usually use both: the metaobject holds the content, and a metafield points at it.

Metafield Metaobject
What it is One extra field on an existing resource (product, variant, collection, customer, order) A new record type with up to 40 fields
Where it lives On the product, collection or other resource In its own list under Content > Metaobjects
Reuse Belongs to one resource One entry can be linked from any number of resources
Editing Edit it on each product Edit the entry once, and every product that links to it updates
Own web page No Yes, if you turn on web pages for the type
Good for A model number, a care note, a launch date A material, a size chart, a designer, a store location, an FAQ

Sources: Shopify’s custom data overview and its Help Center pages on metafields and metaobjects.

The test is simple. If the same piece of content would otherwise be typed into 30 products and kept in sync by hand, it should be a metaobject.

When should you use a metaobject?

Use a metaobject when the thing you’re describing has several fields that belong together, exists apart from any one product, and is reused. Shopify’s own docs list size charts, author profiles, ingredient lists, warranty information, product highlights and FAQs. A designer profile shared across a range of products is its worked example.

Good candidates on a typical store:

  • Materials or ingredients, each with a composition, care or allergy notes and a swatch.
  • Size charts, one per garment type rather than one per product.
  • Designers, makers or authors, each with a bio, a photo and a link.
  • Store locations or stockists, each with an address, opening hours and a map link.
  • Shared FAQs or warranty terms reused across a product line.

Keep a plain metafield when you need one value on one product, such as a model number. And keep price, stock and anything fulfilment depends on in products, variants and inventory. A metaobject is structured content, not a second inventory system.

Handwritten ingredient cards scattered on a table, each card naming one item such as Sauce, Oil and Olive Oil

One card per ingredient is the right picture of a metaobject: each entry is written once and reused wherever it’s needed.

How do you create a metaobject definition in Shopify?

From your Shopify admin, go to Settings > Custom data, open Metaobjects and click Add definition. Name the type, add its fields and choose its options. Shopify’s building guide also lets you start from Content > Metaobjects.

For the Material example:

Field name Field type Why this type
Name Single line text The display name, such as “Organic cotton”
Composition Single line text “100% organic cotton”, shown under the name
Care Multi-line text Washing and drying instructions
Swatch File (image) A close-up of the fabric

Metaobject fields use the same data types as metafields. That includes references to products, collections, files and other metaobjects, and a list version of most types.

Then the options. Shopify lists them on its options page:

  1. Storefronts access. Turn it on. Shopify’s Help Center says it lets you use the metaobject “in your Online Store either through Liquid or the Storefront API”.
  2. Active-draft status. Turn it on, so an entry can be prepared as a draft before it goes live.
  3. Translations. Turn it on if the store sells in more than one language.
  4. Publish entries as web pages. Optional. It gives every entry its own URL; see the web pages section below.

Choose the type’s handle carefully, because Liquid and the APIs refer to it. material is better than materials-v2-new.

How do you add metaobject entries?

Go to Content > Metaobjects, open the Material type and click Add entry. Fill in the fields and save. Entries created in the admin are Active by default, according to Shopify’s guide to creating entries, so set one to Draft if it isn’t ready.

Each entry gets a handle, such as organic-cotton. You’ll use it in Liquid, so keep handles short, lowercase and hyphenated, and don’t rename them once the theme refers to them.

How do you connect a metaobject to products?

Create a product metafield whose type is a metaobject reference, then pick entries on each product. For Material:

  1. Go to Settings > Custom data > Products and click Add definition.
  2. Name it “Materials”. Shopify fills in the key custom.materials.
  3. Choose the type Metaobject, select the Material definition and choose List of entries, because one garment can use several fabrics.
  4. Save. Open any product, find Materials in the metafields section and pick its entries.

To show them without code, open the theme editor, add or select a block on the product template and click Connect dynamic source. Shopify’s guide to connecting metaobjects adds one rule: the field’s type has to match the type of content the block accepts. A text block takes a text field, and an image block takes the swatch.

This needs an Online Store 2.0 theme or a newer theme-blocks theme such as Horizon. Shopify’s theme versions page says vintage themes don’t support dynamic sources, so on those it takes Liquid.

How one Shopify metaobject reaches the storefront. A Material definition with four fields: name, composition, care and swatch. Three entries: Organic cotton, Linen and Recycled polyester. A product metafield, custom.materials, links products to entries: the Oxford shirt to Organic cotton, the summer dress to Linen and Organic cotton. The storefront shows them through a theme block with a dynamic source, through Liquid, or as each entry’s own web page. Editing an entry once updates every product that references it

Diagram — one definition, many entries, linked to products through a metafield and shown in three ways.

How do you show metaobjects in Liquid?

There are three ways in, and most themes use the first.

1. Through the product’s metafield. This is the normal case on a product page:

{%- assign materials = product.metafields.custom.materials.value -%}
{%- if materials != blank -%}
  <ul class="materials">
    {%- for material in materials -%}
      <li>
        {%- if material.swatch.value != blank -%}
          {{ material.swatch.value | image_url: width: 96 | image_tag: alt: material.name.value }}
        {%- endif -%}
        <strong>{{ material.name.value }}</strong>
        <span>{{ material.composition.value }}</span>
      </li>
    {%- endfor -%}
  </ul>
{%- endif -%}

2. One entry directly, by handle. Useful for a single shared block, such as a care guide in the footer:

{%- assign cotton = metaobjects.material['organic-cotton'] -%}
{%- if cotton -%}
  <p>{{ cotton.care.value | newline_to_br }}</p>
{%- endif -%}

3. Every entry of a type. For a “Our materials” page, loop over .values inside paginate:

{%- paginate metaobjects.material.values by 50 -%}
  {%- for material in metaobjects.material.values -%}
    <a href="{{ material.system.url }}">{{ material.name.value }}</a>
  {%- endfor -%}
  {{ paginate | default_pagination }}
{%- endpaginate -%}

material.system.url is only set when the type publishes its entries as web pages, according to Shopify’s Liquid reference for metaobject_system. If a type uses Active-draft status, draft entries come back as nil and are skipped in loops, so a half-finished entry never leaks onto the storefront.

The Liquid limits catch people out, so here they are per page render, from Shopify’s metaobject limits page:

Liquid access Limit
Looping over .values or a list reference without paginate 50 entries
Looping with paginate 250 entries per page
Unique entries per type 1,000
Unique handles per type through metaobjects.TYPE[handle] 20
Definitions through the metaobjects object 50

Can a metaobject have its own web page?

Yes. Turn on Publish entries as web pages in the type’s options and every Active entry gets its own URL, in the form /pages/<type-url-handle>/<entry-handle>. A Material type with the URL handle materials would give /pages/materials/linen. Shopify’s guide to metaobject web pages covers the setup.

What you get:

  • A template at templates/metaobject/material.json, which you design once in the theme editor for every entry of the type.
  • SEO fields. You choose which fields become the page title and meta description, and you can edit each entry’s URL handle under “Search engine listing”.
  • Sitemap entries. Shopify’s capabilities docs say renderable entries are included in the store’s sitemap.xml.

This is the most underused part of metaobjects. A page for each designer, ingredient, material or store location is a page that can rank for searches like “what is Tencel” or “[brand] stockists in Manchester”. It also links naturally to the products that use it. Our Shopify SEO guide covers what makes such a page worth indexing. The short answer is real content, not a name and a photo.

What are the limits on Shopify metaobjects?

Limit Value
Definitions per store 128 on Basic, Shopify and Advanced; 256 on Plus and Enterprise
Fields per definition 40
Entries per definition 1,000,000
Entries one list metafield can reference 1,024
Shopify’s standard definitions Don’t count towards the limits

Source: Shopify’s metaobject limits page, checked on 17 November 2026.

The entry cap went up recently. Shopify’s changelog of 24 October 2025 raised it to 1,000,000 per definition, removing “previous plan-based restrictions of 64,000 (non-Plus) and 128,000 (Plus)”. Older tutorials that quote the lower caps are out of date.

Is your store already using metaobjects?

Yes, if your products have category metafields such as Color or Fabric. Shopify’s Help Center says “category metafields use metaobjects and metaobject entries for the values”. Each value maps to a category in Shopify’s Standard Product Taxonomy. That is why renaming a colour entry from Black to Graphite changes it on every product that uses it.

The colour swatches many themes show on product options work the same way. They come from a standard definition, shopify--color-pattern, linked to the shopify.color-pattern product metafield. Shopify reserves these standard types, and they don’t count towards your 128 or 256.

Before you build a custom Colour or Material type, check whether a category metafield already covers it. If it does, use Shopify’s version and save your own types for what the taxonomy doesn’t have, like designers, size charts or store locations. Otherwise the same fact ends up in two places that drift apart.

Metaobjects for developers: the APIs and app-owned types

The Admin GraphQL API (stable version 2026-10) creates and edits everything the admin can. metaobjectUpsert is the one to know for imports, because it “creates or updates a Metaobject based on its handle”, so a re-run doesn’t create duplicates:

mutation UpsertMaterial {
  metaobjectUpsert(
    handle: { type: "material", handle: "organic-cotton" }
    metaobject: {
      fields: [
        { key: "name", value: "Organic cotton" }
        { key: "composition", value: "100% organic cotton" }
      ]
    }
  ) {
    metaobject { id handle }
    userErrors { field message code }
  }
}

Four things worth knowing in 2026:

  • The Storefront API (for headless stores) returns only Active entries of types whose storefront access is PUBLIC_READ, and needs the unauthenticated_read_metaobjects scope. See the metaobjects query.
  • The new values input (API version 2026-07) sets fields as one JSON object. Shopify’s changelog warns that “omitted keys are cleared”, so send the whole entry, not just the field you changed.
  • App-owned types use the reserved $app: prefix and can be declared in shopify.app.toml. A [metaobjects.app.author] block creates the type $app:author. Shopify’s guide notes these declarative definitions are read-only through the Admin API. Since the Spring ’26 Edition, they need no access scopes.
  • Bulk imports. Shopify’s Help Center doesn’t describe a CSV import for metaobject entries. Large catalogues are loaded through the API, as above, or with an import app.

A developer points at lines of code on an upright tablet screen, a mechanical keyboard and a second monitor on the desk

Upsert by handle, so an import can be run twice without creating duplicate entries.

Common metaobject mistakes

  1. Free text where a reference belongs. A product’s material typed as text can’t be filtered, reused or renamed in one place. Make it a reference to an entry.
  2. Storefronts access left off. Shopify’s Help Center ties both Liquid and Storefront API use to this option, and a headless storefront can’t read the type at all without it. Turn it on for any type the store shows.
  3. Entries left in Draft. If the type uses Active-draft status, drafts return nil in Liquid.
  4. Looping past 50 without paginate. The 51st entry onwards silently doesn’t render.
  5. One type per collection. “Summer materials” and “Winter materials” should be one Material type, perhaps with a season field.
  6. Renaming handles after launch. Liquid that refers to metaobjects.material['organic-cotton'] breaks when the handle changes.
  7. Building a custom type Shopify already has. Check the category metafields and standard definitions first.

When it’s worth getting help

Most stores can set up one or two metaobjects themselves in an afternoon. It’s worth bringing in a developer when the content model spans several types that reference each other, when a vintage theme needs Liquid to show anything, or when a large catalogue has to be imported cleanly.

Designing metafields and metaobjects as a content model is part of our Shopify theme development work; see pricing. If you’re weighing a theme change against an app or a headless build, our theme vs app vs headless guide sets out the trade-offs. Or book a free 30-minute call and we’ll look at your catalogue with you.

FAQs

What is a metaobject in Shopify?

A metaobject is a custom content type you define in Shopify, such as a material, designer or size chart, with up to 40 fields. You create entries of that type under Content > Metaobjects and link them to products, collections or pages through metafields. Editing an entry once updates everywhere it’s used.

What is the difference between metafields and metaobjects in Shopify?

A metafield adds one extra field to a resource Shopify already has, such as a product or customer. A metaobject is a separate record type with several fields of its own. Metaobjects are usually linked to products through a metafield whose type is a metaobject reference.

How many metaobjects can a Shopify store have?

A store can create 128 metaobject definitions on Basic, Shopify and Advanced plans, and 256 on Plus and Enterprise. Each definition can have up to 40 fields and up to 1,000,000 entries. Shopify’s standard definitions don’t count towards these limits.

How do I display metaobjects on my Shopify store?

On an Online Store 2.0 or Horizon theme, link entries to products with a metaobject reference metafield, then use Connect dynamic source on a theme block. Without dynamic sources, use Liquid, for example product.metafields.custom.materials.value. You can also publish each entry as its own web page.

Can Shopify metaobjects have their own pages?

Yes. Turn on “Publish entries as web pages” in the metaobject’s options. Each Active entry gets a URL in the form /pages/type-handle/entry-handle, uses the template templates/metaobject/type.json, and has its own SEO title and description.

Why is my metaobject not showing on the storefront?

Check three things. Storefronts access must be on for the definition, and the entry must be Active, not Draft. A loop without paginate shows only the first 50 entries. On a vintage theme there are no dynamic sources, so the theme needs Liquid to show it.

Can I import metaobject entries from a CSV?

Shopify’s Help Center doesn’t describe a CSV import for metaobject entries. Large sets are usually loaded through the Admin API with metaobjectUpsert, which creates or updates entries by handle, or with a third-party import app.

Written by Vibhora

Shopify development, branding, custom apps, SEO, paid ads and store care for small and growing brands - one team, fixed published prices.

Explore Theme Development

Free checklist

The 25-point Shopify store audit checklist

The same checks we run in a paid audit — performance, SEO and answer engines, conversion, accessibility and code — as one page you can work through yourself or hand to your developer.

We store your address to follow up about the checklist and Vibhora's services. No newsletter, no list sold; reply to any message to stop.

All insights

Black Friday · Cyber Monday

50% off every project over $499

A new store, an app, a brand or a rebuild, at half price. Book your free call before the clock runs out.

--days
--hrs
--min
--sec

Black Friday 27 Nov · Cyber Monday 30 Nov · Offer ends 1 Dec

Starting pricesHalf off

  • Shopify themewas $999now $499
  • WordPress sitewas $799now $399
  • Headless storefrontwas $2,999now $1,499

Book before 1 Dec · scoped on a free call

Ends in--d --h --m --s

50% off every project over $499

Our biggest deal of the year. Book a free call before 1 December and your new store, app, brand or rebuild is half price.

  • Shopify themefromwas $999now $499
  • WordPress sitefromwas $799now $399
  • Headless storefrontfromwas $2,999now $1,499

Free 30-minute call · Book before 1 Dec

Prefer to write? Send your project details

250+ brands shipped85+ storefronts maintained

For one-time projects of $500 or more, booked by 30 November 2026 (IST). Monthly retainers and plans are not included. We scope it on the free 30-minute call.