What is a Shopify metaobject?

Picture a clothing store with fifty T-shirts that share the same size guide. If the guide is stored inside each product, there are fifty copies, and the day a measurement changes you have to fix fifty product pages and trust you did not forget any. A Shopify metaobject solves that: the guide is stored once, as a record of its own, and each T-shirt links to it. It matters because it decides how much it costs to keep up to date the data that repeats across your catalog, and because data maintained in a single place has fewer chances to go stale on a product page.

How it works

Shopify presents metaobjects as custom data structures with several related fields. Unlike metafields, which add a single field to a resource that already exists, a metaobject is a new data type that can be referenced from anywhere in the store. Shopify's rule is short: metaobjects for complex, multi-field data, metafields for a single field.⁠^{[1]Shopify.dev. Metaobjects} As examples, its developer documentation cites size guides, author profiles, ingredient lists and warranty information,⁠^{[1]Shopify.dev. Metaobjects} and its help center adds a product's key features with an icon, title and description, influencer profiles, frequently asked questions and event appearances.⁠^{[2]Shopify Help Center. Metaobjects}

A metaobject has two parts:

The two parts and their locations are as Shopify describes them.⁠^{[1]Shopify.dev. Metaobjects}⁠^{[2]Shopify Help Center. Metaobjects} As with metafields, the prefix says whose data it is: an app's definitions use the reserved $app prefix, the merchant's use non-reserved prefixes such as custom, and Shopify maintains its own. And there is one permission worth checking on day one: storefront access is none by default, and you have to open it with public_read to read the entries from outside the admin.⁠^{[1]Shopify.dev. Metaobjects}

How it links to a product

A product does not contain the metaobject: it points to it with a reference-type metafield. Shopify offers three types:⁠^{[3]Shopify.dev. List of data types}

In addition, a definition can turn on capabilities that change its behavior. Publishable lets you set each entry as draft or active; translatable opens the entries to Shopify's translation tools; renderable exposes SEO fields to Liquid and to the Storefront API and includes the entries in the store's sitemap; and Online Store assigns the entries a theme template and a URL of their own.⁠^{[4]Shopify.dev. Use metaobject capabilities} With those last two, a metaobject stops being just a piece of data and becomes a page: Shopify frames it as a way to create repeatable landing pages, such as one for each of a brand's ambassadors, and lets you choose which fields make up the page title and the meta description.⁠^{[5]Shopify Help Center. Metaobject webpages}

In a store

Fictional example. The clothing store creates a size_guide definition with three fields: name (single-line text), table (multi-line text) and tip (single-line text). It creates one entry, "Cotton T-shirts", and on each T-shirt it fills in a product metafield, custom.size_guide, of type metaobject_reference. The theme's product section prints it like this:

{% assign guide = product.metafields.custom.size_guide.value %}
{% if guide %}
  <h2>{{ guide.name.value }}</h2>
  <p>{{ guide.tip.value }}</p>
{% endif %}

In Liquid, each field of a metaobject is read with its key and its value, as in metaobjects['highlights']['washable'].image.value.⁠^{[6]Shopify.dev. Liquid objects: metaobject} For a simple case there is a shortcut: the metafield_text filter accepts metaobject references with a required field parameter, which can only point to a single-line text field.⁠^{[7]Shopify.dev. Liquid filters: metafield_text} What changes compared with storing the guide in each product shows up in a table:

How to check it

1. Open the definition in the custom data settings: note its type, its fields and whether storefront access is open.⁠^{[1]Shopify.dev. Metaobjects}⁠^{[2]Shopify Help Center. Metaobjects}
2. Open the entry in Content › Metaobjects and check its values and, if the definition is publishable, that its status is active.⁠^{[4]Shopify.dev. Use metaobject capabilities}
3. Open a product and check that its reference metafield points to that entry and not to another one from the same definition.⁠^{[3]Shopify.dev. List of data types}
4. Search the theme for the metafield's namespace and key, or for the block connected to it from the theme editor. If nothing reads them, the data is stored but not published.
5. Open the product page's source code (not the inspector) and search for a value from the entry. If it appears, it travels in the initial HTML; if not, go back to the step that failed.

Related concept: metafields

A metafield extends a resource that already exists, such as a product, with one more field; a metaobject is a record type of its own with several fields that does not belong to any resource.⁠^{[1]Shopify.dev. Metaobjects} They do not compete: they work together, because the reference metafield is the bridge between the product and the metaobject entry.⁠^{[3]Shopify.dev. List of data types}

To keep going, the guide from metafield to published page follows a piece of Shopify data all the way to the product page's HTML, and the publishing by platform reading path orders the rest of the terms.