Shopify Metaobjects: The Complete Developer Guide

Shopify metaobjects are custom data structures that let you store, organize, and reuse structured content directly within the Shopify admin. They turn your store into a native headless CMS -- no third-party apps required.

This guide covers everything you need to know to master metaobjects: from creation to display, including GraphQL queries and SEO best practices.

What Are Shopify Metaobjects?

A Shopify metaobject is a standalone data entity that groups multiple fields into a single data model. Unlike individual custom fields limited to one type of information, metaobjects form coherent, reusable structured data objects.

In practice, a metaobject works like a mini database built into your store. Each metaobject has its own definition (the schema that determines the fields) and its own entries (the actual data). This modular approach lets you create rich content -- author profiles, size guides, ingredient cards, technical specifications, promotional banners, lookbooks -- without relying on third-party apps.

For teams looking for an alternative to an external CMS, metaobjects provide a native headless content management solution integrated directly into the Shopify ecosystem. Metaobjects are available on all Shopify plans, including Shopify Plus where they are particularly useful for managing content at scale.

Metaobjects vs. Metafields: What Is the Difference?

The confusion between metafields and metaobjects is common. Here is the essential distinction:

Expert tip: if you are extending an existing object with an extra field (e.g., a launch date on a product), use a metafield. If you are creating a new type of reusable content across your store (e.g., team profiles, a store locator), choose a metaobject.

The concept of a "group of metafields" does not exist natively in Shopify. The admin interface allows visual organization of metafields, but only metaobjects offer a true standalone entity structure with their own handle and capabilities.

Core Concepts: Definitions, Entries, and Handles

Every metaobject relies on two components:

• The definition: created in Settings > Custom data, it determines the data model structure. You define a name (e.g., "Authors"), a type, and a list of fields. Each field has a field type (single_line_text, file_reference, url, rich_text_area, number_integer, number_decimal, etc.), a name, an optional description, and validation rules.
• The entries: managed in Content > Metaobjects, they contain the actual data. Each entry is an instance of the definition -- for example, a specific author with their name, biography, and photo.

A special field called the display name is assigned to one of the text fields in the definition. It serves as a visual identifier to quickly distinguish entries in the admin interface.

Key limitations:

• The handle of a metaobject definition cannot be changed after creation.
• Name your fields in English without special characters to ensure code longevity.
• Shopify imposes a limit of 256 metaobject definitions and a maximum number of entries per definition.
• Changing an existing field's type is very limited. Plan your data structure carefully.

Capabilities: Publishable, Storefront Access, and Renderable

Capabilities determine how and where your metaobjects are accessible. Each one enables a distinct feature:

• Publishable

  • Function: adds a publication status (active or draft) to entries.
  • Practical impact: only active entries are visible on the storefront. A draft entry is invisible and returns nil in Liquid.

• Storefront Access

  • Function: authorizes access to metaobjects from the Storefront GraphQL API.
  • Practical impact: essential for headless commerce architectures. Without this capability, data is only accessible via the Admin API. This is the most common mistake when setting up metaobjects for headless projects.

• Renderable

  • Function: allows associating a theme template with a metaobject.
  • Practical impact: each metaobject entry becomes a standalone web page with its own URL generated from the handle. Displayed as "Web Pages" in the admin interface, this option creates dynamic pages (author profiles, store pages) without modifying theme code.

Dynamic sources complement these capabilities. They let you connect a metaobject entry to a theme section directly in the theme editor of Dawn or any Online Store 2.0-compatible theme, with no code required. A merchant can link a specific size guide to a product through the visual interface.

Why Use Metaobjects? 6 Practical Use Cases

Metaobjects shine when you need to manage structured, reusable content across your Shopify store. Here are six scenarios where they outperform standard metafields.

1. Reusable Author and Team Profiles

Create rich profile cards for your authors, designers, or brand ambassadors. Each profile contains a name, biography, photo (file_reference to leverage the Shopify CDN), social media links, and a list of associated products (list.product_reference). Use a metaobject_reference field on your products or blog posts to link to the corresponding profile.

2. Size Guides and Technical Specifications

Define a "Size Guide" metaobject with fields for each measurement. Configure a metaobject_reference field on your products to accept "Size Guide" entries. The dynamic sources in Online Store 2.0 let the merchant select the right guide directly in the theme editor. A single guide can be shared across dozens of similar products, and any update propagates instantly.

3. No-Code Editable Sections (Banners, Hero Sections)

Use metaobjects with the Renderable capability to create promotional banners or hero sections managed from Content > Metaobjects. Marketing teams can modify content -- text, images, links, campaign dates -- without touching theme code or involving a developer.

4. Modular Editorial Content (Lookbooks, Ingredients)

Metaobjects are ideal for structuring seasonal lookbooks, ingredient lists, or material cards. Each entry contains a title, a rich description (rich_text_area), an image (file_reference), and references to related products via product_reference. This modular content can be inserted across multiple site pages simultaneously.

5. Reusable FAQs per Product or Collection

Create a "FAQ" metaobject with question (single_line_text) and answer (rich_text_area) fields. Associate one or more entries to each product or collection via a list.metaobject_reference field. This approach:

• Eliminates content duplication and centralizes maintenance
• Enables generating FAQPage structured data (schema.org) on the page that displays the questions
• Helps target "Rich Snippet" and "People Also Ask" positions in Google

The FAQPage structured data must be generated on the final page (product, collection) that displays the questions -- not in the metaobject definition itself.

6. Store Locator and Points of Sale

Define a "Store" metaobject with fields for address (multiple single_line_text fields for street, city, postal code), latitude (number_decimal), and longitude (number_decimal) as two separate fields to ensure interoperability with mapping APIs (Google Maps, Mapbox), opening hours, and a photo (file_reference).

Enable the Renderable capability to generate a dedicated page per store with its own handle and URL. Combine with the Storefront GraphQL API to display an interactive map on a headless site. This approach decouples data management (by staff in Shopify) from data consumption (by the front-end app via the API).

Tutorial: Create Your Shopify Metaobjects Step by Step

This tutorial guides you through creating a complete "Author" metaobject, from definition to display on your store.

Step 1: Define the Metaobject Structure

1. In the Shopify admin, go to Settings > Custom data.
2. Click Add definition in the Metaobjects section.
3. Name the definition (e.g., authors). The handle is generated automatically and cannot be changed after saving.
4. Add the following fields:
   • name: type single_line_text -- the author's name (check Display name)
   • biography: type multi_line_text -- the biography
   • avatar: type file_reference -- the profile photo (served from the Shopify CDN)
   • social_url: type url -- link to a social profile
5. In the Options section, enable the required capabilities:
   • Storefront access to make data available via the Storefront API or in a headless architecture
   • Publishable to control entry visibility (active / draft)
   • Renderable if you want to generate a page per author -- essential for SEO if building a profile directory
6. Save the definition.

Naming convention: always use English and snake_case (e.g., author_name, cover_image) for all field handles. This is an industry standard that ensures compatibility with tools, APIs, and Liquid code.

Important: once a field is saved in the definition, changing its type is very limited. Plan your data structure carefully to avoid complex migrations later.

Step 2: Create the Entries

1. Go to Content > Metaobjects.
2. Select the "Authors" definition.
3. Click Add entry.
4. Fill in the fields: name, biography, upload the image.
5. If the Publishable capability is active, set the status to Active to make the entry visible.
6. Save.

Repeat for each author. For bulk imports, use the Admin GraphQL API with the metaobjectCreate mutation or the Shopify CLI to automate the process through migration scripts or a CI/CD workflow.

Step 3: Reference the Metaobject from a Product or Page

To display metaobject data on your store, you need to create a link between the resource (product, blog post, page) and the metaobject entry:

1. In Settings > Custom data, select the target resource (e.g., Blog posts).
2. Add a metafield of type metaobject_reference pointing to the "Authors" definition.
3. On each blog post, select the corresponding author entry in the new field.

The entry is now linked. The next step is displaying this data in your theme or front-end application.

Displaying Metaobjects: Native Liquid and Headless GraphQL

Once your metaobjects are created and referenced, the next step is display. Shopify offers multiple approaches depending on your technical architecture.

Native Liquid Display in Online Store 2.0 Themes

In an Online Store 2.0-compatible theme, metaobjects are accessible via the Liquid template language. Data access is native and adds no additional HTTP request.

Display a simple reference (e.g., an author name on a blog post):

{%- comment -%} Retrieve the metaobject author reference from the article metafield {%- endcomment -%}
{% assign author = article.metafields.custom.author_reference.value %}
 
<div class="author-card">
  {%- comment -%} file_reference field: image served from the Shopify CDN {%- endcomment -%}
  <img src="{{ author.avatar.value | image_url: width: 200 }}" alt="{{ author.name.value }}">
 
  {%- comment -%} Simple text fields from the metaobject {%- endcomment -%}
  <p>{{ author.name.value }}</p>
  <p>{{ author.biography.value }}</p>
</div>

Iterate over a list of references (e.g., multiple materials on a product):

{%- comment -%} Loop over a list.metaobject_reference field {%- endcomment -%}
{% for material in product.metafields.custom.materials.value %}
  <div class="material-card">
    <h3>{{ material.name.value }}</h3>
    <p>{{ material.description.value }}</p>
  </div>
{% endfor %}

Dynamic sources also let you connect metaobjects to theme sections directly in the editor, without writing Liquid. The merchant selects the desired entry in the visual theme interface.

Headless Display via the Storefront GraphQL API

For a headless commerce architecture, metaobjects are accessible via the Storefront GraphQL API. The Storefront access capability must be enabled on the definition. Queries depend on the API version used (e.g., 2025-01), and available fields may vary between versions.

GraphQL query to retrieve a metaobject by handle:

# Retrieve a specific entry by its handle and type
query GetAuthor {
  metaobject(handle: { handle: "bastien-allain", type: "authors" }) {
    fields {
      key
      value
      reference {
        # Fragment to access referenced image data
        ... on MediaImage {
          image {
            url
            altText
          }
        }
      }
    }
  }
}

Query to list all entries of a type:

# Paginated listing of all entries of type "authors"
query ListAuthors {
  metaobjects(type: "authors", first: 50) {
    edges {
      node {
        handle
        fields {
          key
          value
        }
      }
    }
  }
}

These queries integrate into any front-end framework -- React, Next.js, Vue, Nuxt -- via a GraphQL client like @shopify/storefront-api-client (which handles configuration, typing, and authentication headers automatically) or Apollo. This approach fully decouples content management (in the Shopify admin) from display (in the front-end app), which is the core principle of headless architecture.

Creating Dynamic Pages from Metaobjects

With the Renderable capability enabled, each metaobject entry generates a page with its own URL in the format /pages/{handle}. Shopify lets you associate a specific theme template with each metaobject type.

For a headless site, replicate this mechanism by using the metaobjects query to list all entries and generate dynamic routes client-side (e.g., getStaticPaths in Next.js or useAsyncData in Nuxt).

Important limitation: pages generated by Renderable are not automatically added to the Shopify XML sitemap. You must add these URLs manually or through a dedicated app to ensure their indexation by search engines.

Advanced Techniques and Best Practices

Metaobjects and SEO: Generating Schema.org (JSON-LD)

Metaobjects do not automatically generate structured data. To leverage their SEO potential, you must generate JSON-LD markup on the pages that display metaobject data.

For example, for a "FAQ" metaobject displayed on a product page, generate the FAQPage schema in the Liquid template:

{%- comment -%} Generate FAQPage schema from FAQ metaobjects {%- endcomment -%}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {%- for faq in product.metafields.custom.faqs.value -%}
    {
      "@type": "Question",
      "name": {{ faq.question.value | json }},
      "acceptedAnswer": {
        "@type": "Answer",
        "text": {{ faq.answer.value | json }}
      }
    }{%- unless forloop.last -%},{%- endunless -%}
    {%- endfor -%}
  ]
}
</script>

This technique also applies to Person schemas (author profiles), LocalBusiness (store locator), or Product (enriched technical specifications). It is the recommended method for targeting Rich Snippet positions in search results.

Performance Impact: Are Metaobjects Fast?

Yes, metaobject performance is excellent in Liquid. Data access is native, with no additional HTTP request. Performance is equivalent to that of metafields.

In a headless architecture, each Storefront GraphQL API call is a network request. To optimize performance:

• Limit query depth: avoid nested references beyond 2 levels to control GraphQL resolver complexity and API request cost.
• Use pagination: fetch entries in batches (first: 10) rather than loading all entries of a type at once.
• Cache responses: implement a caching layer (ISR in Next.js, SWR, or an edge CDN) to reduce API calls.
• Select fields: only request the fields you need in your GraphQL queries.

Migrating from Complex Metafields to Metaobjects

If you already use metafields to store complex, repetitive data (e.g., product specifications duplicated across multiple listings), migrating to metaobjects simplifies management.

The recommended approach:

1. Audit your existing metafields to identify duplicated data or repeating field groups.
2. Create the corresponding metaobject definition with the same field types.
3. Migrate the data via the Admin GraphQL API: create metaobject entries (metaobjectCreate), then update product metafields to point to the new entries (metaobject_reference).
4. Test the display in your theme or front-end application before deleting the old metafields.

Expert tip: start with a single product type and validate the result end-to-end before running a script across the entire catalog. This prevents data corruption at scale.

Managing Metaobjects with the Admin GraphQL API

The Admin GraphQL API provides full control over metaobjects. Here are the essential mutations and queries:

• metaobjectDefinitionCreate: create a new definition
• metaobjectCreate: add an entry
• metaobjectUpdate: modify an existing entry
• metaobjectDelete: delete an entry
• metaobjects (query): list entries with filters and pagination

Example query to list entries:

# List metaobjects of type "authors" using the Admin API
query ListAuthorsAdmin {
  metaobjects(type: "authors", first: 10) {
    edges {
      node {
        id
        handle
        displayName
        fields {
          key
          value
        }
      }
    }
  }
}

These operations integrate into migration scripts, CI/CD workflows, or custom Shopify apps. The Shopify CLI also lets you manage definitions via local configuration files -- the preferred approach for teams that version their code and deploy through automated pipelines.

Frequently Asked Questions About Shopify Metaobjects

What is the difference between a metaobject and a metafield in Shopify?

A metafield is a single field attached to an existing resource (product, collection, order). It extends an object already present in Shopify. A metaobject is a standalone entity with its own definition, entries, and handle.

The concept of a "group of metafields" is not a native Shopify entity -- it is a visual organization in the admin interface. Metaobjects, by contrast, are true structured objects with publication capabilities, API access, and page generation features.

In summary: a metafield extends an existing object. A metaobject creates a new type of object.

How do you query metaobjects with the GraphQL Storefront API?

The Storefront access capability must be enabled on the metaobject definition. Then, use the metaobject query to retrieve a specific entry by its handle and type, or the metaobjects query to list all entries of a given type.

# Example: retrieve a specific author via the Storefront API
query {
  metaobject(handle: { handle: "bastien-allain", type: "authors" }) {
    fields {
      key
      value
    }
  }
}

Each field is accessible through the fields array containing key / value pairs. For reference-type fields (images, products), use GraphQL fragments (... on MediaImage, ... on Product) to access linked data. See our Storefront API GraphQL guide for a deeper dive.

Can you create dynamic pages from metaobjects?

Yes. Enable the Renderable capability on the metaobject definition. Shopify then generates a unique page for each entry, with a URL based on the entry's handle. You can associate a specific theme template with that metaobject type to customize the display.

This approach is ideal for creating author pages, store profile pages, or brand pages without developing custom routing logic.

Important note: these pages are not automatically added to the Shopify XML sitemap. You must add them manually or via a dedicated app to ensure their indexation.

When should you use a metaobject in Shopify?

The most common use cases:

• Team or ambassador profiles: reusable cards with biography, photo, and social links
• Size guides: shared across multiple products, updated in a single location
• Reusable FAQs: centralize questions/answers and generate valid FAQPage schema
• Store locators: with GPS coordinates, hours, and dedicated pages per location
• Ingredient or material cards: for cosmetics, fashion, and food industries
• Promotional banners: editable without code by marketing teams
• Seasonal lookbooks: with product references and rich editorial content

Metaobjects are the right choice whenever content needs to be structured, reusable, and accessible from multiple locations across your store. To learn how to integrate them into a complete headless architecture, see our headless Shopify guide or our Shopify headless development services.