# What Is a Shopify Metaobject and When to Use It

> What a Shopify metaobject is, how it differs from a metafield, how it links to your products and how to check that your theme publishes it on the product page.

URL: https://clione.ai/glossary/shopify-metaobject/
Lang: en

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](/glossary/product-page/) 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](/glossary/product-page/).

## How it works

Shopify presents metaobjects as custom data structures with several related fields. Unlike [metafields](/glossary/shopify-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**.[^shopify-metaobjects-dev] As examples, its developer documentation cites size guides, author profiles, ingredient lists and warranty information,[^shopify-metaobjects-dev] and its help center adds a product's key features with an icon, title and description, influencer profiles, frequently asked questions and event appearances.[^shopify-help-metaobjects]

A metaobject has two parts:

| Part       | What it is                                                                                                                           | Where it is managed         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| Definition | The structure: the type, the fields with their data type and validations, the access permissions and the field that names each entry | In the custom data settings |
| Entries    | Each specific record, with its identifier, its handle, its display name and the value of each field                                  | In Content › Metaobjects    |

The two parts and their locations are as Shopify describes them.[^shopify-metaobjects-dev][^shopify-help-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.[^shopify-metaobjects-dev]

## 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:[^metafield-types]

| Metafield type              | What it points to                                                 |
| --------------------------- | ----------------------------------------------------------------- |
| `metaobject_reference`      | One entry. A validation sets which definition it has to belong to |
| `list.metaobject_reference` | One or several entries, all from the same definition              |
| `mixed_reference`           | One entry that can belong to different definitions                |

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](/glossary/shopify-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.[^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](/glossary/meta-title/) and the [meta description](/glossary/meta-description/).[^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:

```liquid
{% 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`.[^liquid-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.[^metafield-text-filter] What changes compared with storing the guide in each product shows up in a table:

| With the size guide in… (fictional example) | Copies of the guide | To fix a measurement          |
| ------------------------------------------- | ------------------- | ----------------------------- |
| A text metafield on each T-shirt            | One per T-shirt     | Edit each T-shirt, one by one |
| A metaobject linked from each T-shirt       | One for all         | Edit the entry once           |


Creating the entry does not publish it. For it to reach a product page you need three things: a reference metafield on the product that points to it, a theme template that reads it and, if the definition has the publishable capability, the entry has to be active: **a draft entry returns `nil` in Liquid**, so the product page prints nothing and does not throw an error either.[^liquid-metaobject][^metaobject-capabilities]


## How to check it

1. **Open the definition** in the custom data settings: note its type, its fields and whether storefront access is open.[^shopify-metaobjects-dev][^shopify-help-metaobjects]
2. **Open the entry** in Content › Metaobjects and check its values and, if the definition is publishable, that its status is active.[^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.[^metafield-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.[^shopify-metaobjects-dev] They do not compete: they work together, because **the reference metafield is the bridge** between the product and the metaobject entry.[^metafield-types]

To keep going, the guide [from metafield to published page](/guides/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](/learn/publishing-by-platform/) orders the rest of the terms.