Back to Blog
Contact Me
Shopify Metaobjects Complete Developer Guide
Developer Deep Dive

Shopify Metaobjects: The Complete 2026 Developer's Guide to Custom Content Architecture

By Tejas Kedare • Updated: January 2026 • 35 min read

Shopify Metaobjects are one of the most powerful yet underutilized features in the Shopify ecosystem. While most merchants know about metafields (custom data attached to products, customers, or orders), Metaobjects take this further by allowing you to create entirely new content types with their own schemas, entries, and relationships. Think of it as building your own mini-CMS inside Shopify—without third-party apps, monthly fees, or external databases.

This comprehensive guide covers everything from basic concepts to advanced implementation patterns. Whether you're building size guides, store locators, team member pages, ingredient databases, or complex product specifications, Metaobjects can handle it. By the end of this guide, you'll understand when to use Metaobjects vs. Metafields, how to design effective schemas, and how to render them beautifully in your theme.

Complete Developer's Guide Contents

1. What Are Shopify Metaobjects?

Metaobjects are custom content types that you define in your Shopify store. Unlike metafields, which attach custom data to existing resources (like products or customers), Metaobjects are standalone entries with their own structure.

The Mental Model

Think of Metaobjects like this:

  • Metaobject Definition: A template or "blueprint" that describes what fields an entry should have. Like a database table schema.
  • Metaobject Entry: An actual instance of that definition, filled with data. Like a row in a database table.

Example: You create a "Size Guide" definition with fields like "Title", "Description", "Size Chart Image", and "Measurements Table". Then you create entries: "T-Shirt Size Guide", "Jeans Size Guide", "Shoes Size Guide". Each entry follows the same structure but contains different data.

Why They Exist

Before Metaobjects, if you wanted to create structured content outside of the product/collection model, you had three options:

  1. Third-party CMS apps: Contentful, Prismic, or custom solutions. Expensive and adds complexity.
  2. Hack metafields: Store complex JSON in a single metafield. Messy and hard to manage.
  3. Abuse pages/products: Create "fake" products or pages just to store data. Pollutes your catalog.

Metaobjects solve this cleanly by giving you a first-party way to model structured content with proper admin UI, API access, and Liquid integration.

2. Metaobjects vs. Metafields: When to Use Each

This is the most common source of confusion. Let's clarify definitively.

Aspect Metafields Metaobjects
Attachment Attached TO a resource (product, variant, customer, order, collection, etc.) Standalone entries, not attached to any specific resource
Structure Single field per definition Multiple fields per definition (like a mini-database table)
Best For Adding custom attributes to existing resources (product dimensions, warranty info) Creating entirely new content types (size guides, FAQs, team members)
Reusability A metafield value belongs to ONE resource instance A metaobject entry can be referenced by MANY resources
Admin UI Fields appear on the resource's edit page Separate "Content" area in admin with dedicated entry management
Relationships Can reference metaobjects, products, files, etc. Can reference other metaobjects, creating complex data graphs

Decision Framework

Use Metafields when:

  • The data belongs to a specific product/variant/customer/order
  • You're adding a single custom attribute (e.g., "Warranty Period" on products)
  • The data doesn't need to be shared across multiple resources

Use Metaobjects when:

  • You need a reusable content entry that multiple products/pages reference
  • You're creating a new "type" of content (Author, Size Guide, FAQ Set, Store Location)
  • The content has multiple fields that belong together
  • You want non-technical users to manage structured content via admin UI

Pro Tip: Combining Both

The most powerful pattern is using them together. Create a Metaobject for "Size Guide" content. Then add a Metafield to products of type "metaobject_reference" that points to the appropriate Size Guide. This way, 50 T-shirt products can all reference the same "T-Shirt Size Guide" metaobject.

3. Core Concepts and Terminology

Metaobject Definition

The schema or "blueprint" that defines what a metaobject looks like. Created via Admin API or the Shopify admin UI. Contains:

  • Type: A unique identifier (e.g., size_guide, team_member)
  • Name: Human-readable display name
  • Field Definitions: The fields that entries of this type will have
  • Access Configuration: Which surfaces can read the data (Storefront API, admin, etc.)

Field Types Available

Metaobject fields support the same types as metafields:

  • single_line_text_field
  • multi_line_text_field
  • rich_text_field
  • number_integer
  • number_decimal
  • date
  • date_time
  • boolean
  • color
  • url
  • file_reference (images, PDFs)
  • product_reference
  • collection_reference
  • page_reference
  • metaobject_reference (references to other metaobjects)
  • json (for complex nested data)
  • list.* (lists of any above type)

Metaobject Entry

An instance of a definition, containing actual data. If "Size Guide" is your definition (the blueprint), then "T-Shirt Size Guide" is an entry (an actual size guide with real content).

Handle

Each entry has a unique handle (like products have handles/slugs). This is used to reference specific entries in Liquid: shop.metaobjects.size_guide['t-shirt']

4. Creating Metaobject Definitions (Schema Design)

Method 1: Via Shopify Admin UI

  1. Go to Settings > Custom data > Metaobjects
  2. Click "Add definition"
  3. Enter a Type (e.g., size_guide) and Name (e.g., "Size Guide")
  4. Add field definitions one by one, specifying name, type, and validation rules
  5. Configure access (enable Storefront API access if you need it on the frontend)
  6. Save

Method 2: Via Admin API (GraphQL)

For programmatic creation (useful for agencies deploying to multiple stores):

GraphQL Mutation: Create Metaobject Definition mutation CreateMetaobjectDefinition { metaobjectDefinitionCreate(definition: { type: "size_guide" name: "Size Guide" description: "Reusable size guide content for products" fieldDefinitions: [ { key: "title" name: "Title" type: "single_line_text_field" validations: [{ name: "min", value: "1" }] } { key: "description" name: "Description" type: "multi_line_text_field" } { key: "chart_image" name: "Size Chart Image" type: "file_reference" validations: [{ name: "file_type_options", value: "[\"Image\"]" }] } { key: "measurements" name: "Measurements JSON" type: "json" description: "Table data for measurements" } ] access: { storefront: ACTIVE admin: MERCHANT_READ_WRITE } }) { metaobjectDefinition { id type name } userErrors { field message } } }

Schema Design Best Practices

  1. Be Specific with Types: Use author not content. Specific types are easier to query and manage.
  2. Use Descriptive Field Keys: short_description not desc1.
  3. Think About Reusability: A "Brand" metaobject could be referenced by multiple product collections.
  4. Enable Storefront Access: If you need to render it on the theme, enable Storefront API access in the definition.
  5. Use Rich Text Wisely: Great for prose content, but harder to style than structured fields.

5. Managing Metaobject Entries

Via Admin UI

Once you have a definition, create entries via:

  1. Go to Content > Metaobjects > [Your Type]
  2. Click "Add entry"
  3. Fill in the field values
  4. Set a handle (URL-friendly identifier)
  5. Save

Merchants can manage entries just like products or pages—no developer needed for day-to-day content updates.

Via Admin API

GraphQL Mutation: Create Metaobject Entry mutation CreateMetaobjectEntry { metaobjectCreate(metaobject: { type: "size_guide" handle: "t-shirt-size-guide" fields: [ { key: "title", value: "T-Shirt Size Guide" } { key: "description", value: "Find your perfect T-shirt fit using our measurement guide below." } { key: "chart_image", value: "gid://shopify/MediaImage/123456789" } { key: "measurements", value: "{\"headers\":[\"Size\",\"Chest\",\"Length\"],\"rows\":[[\"S\",\"36\",\"27\"],[\"M\",\"38\",\"28\"],[\"L\",\"40\",\"29\"]]}" } ] }) { metaobject { id handle } userErrors { field message } } }

6. Rendering Metaobjects in Liquid

This is where Metaobjects become visible to customers. There are several ways to access metaobject data in Liquid.

Method 1: Direct Access via shop.metaobjects

Access a specific entry by its handle:

Liquid: Access Single Metaobject {%- assign size_guide = shop.metaobjects.size_guide['t-shirt-size-guide'] -%} {%- if size_guide -%} <div class="size-guide"> <h2>{{ size_guide.title.value }}</h2> <p>{{ size_guide.description.value }}</p> {%- if size_guide.chart_image.value -%} <img src="{{ size_guide.chart_image.value | image_url: width: 800 }}" alt="{{ size_guide.title.value }}" loading="lazy" > {%- endif -%} </div> {%- endif -%}

Method 2: Loop Through All Entries of a Type

Liquid: Loop All Entries {%- for guide in shop.metaobjects.size_guide -%} <div class="guide-card"> <h3>{{ guide.title.value }}</h3> <a href="#guide-{{ guide.handle }}">View Guide</a> </div> {%- endfor -%}

Method 3: Via Metafield Reference

When a product's metafield points to a metaobject:

Liquid: Metaobject via Product Metafield {%- comment -%} Assumes product has a metafield: custom.size_guide (type: metaobject_reference) {%- endcomment -%} {%- assign product_size_guide = product.metafields.custom.size_guide.value -%} {%- if product_size_guide -%} <details class="size-guide-accordion"> <summary>Size Guide: {{ product_size_guide.title.value }}</summary> <div class="guide-content"> {{ product_size_guide.description.value }} {%- if product_size_guide.chart_image.value -%} {{ product_size_guide.chart_image.value | image_url: width: 600 | image_tag }} {%- endif -%} </div> </details> {%- endif -%}

Rendering JSON Fields

For complex data stored in JSON fields (like measurement tables):

Liquid: Parsing JSON Metaobject Field {%- assign measurements = size_guide.measurements.value -%} {%- if measurements -%} <table class="measurements-table"> <thead> <tr> {%- for header in measurements.headers -%} <th>{{ header }}</th> {%- endfor -%} </tr> </thead> <tbody> {%- for row in measurements.rows -%} <tr> {%- for cell in row -%} <td>{{ cell }}</td> {%- endfor -%} </tr> {%- endfor -%} </tbody> </table> {%- endif -%}

7. Storefront API and Admin API Integration

Storefront API (GraphQL)

For headless implementations (Hydrogen, Gatsby, Next.js), query metaobjects via Storefront API:

Storefront API: Query Metaobjects query GetSizeGuides { metaobjects(type: "size_guide", first: 10) { nodes { id handle fields { key value reference { ... on MediaImage { image { url altText } } } } } } }

Query a Single Metaobject by Handle

Storefront API: Single Metaobject query GetSizeGuide($handle: String!) { metaobject(handle: { type: "size_guide", handle: $handle }) { id handle title: field(key: "title") { value } description: field(key: "description") { value } chartImage: field(key: "chart_image") { reference { ... on MediaImage { image { url(transform: { maxWidth: 800 }) } } } } } }

Admin API for Bulk Operations

For migrations or syncing data:

Admin API: Bulk Query Metaobjects query BulkGetMetaobjects { metaobjects(type: "size_guide", first: 250) { edges { node { id handle fields { key value } } } pageInfo { hasNextPage endCursor } } }

8. Building Relationships Between Metaobjects

One of the most powerful features of Metaobjects is the ability to create relationships—essentially building a relational database within Shopify.

Example: Author and Articles

Metaobject: Author
- name (single_line_text_field)
- bio (multi_line_text_field)
- photo (file_reference)
- social_links (json)

Metaobject: Article
- title (single_line_text_field)
- content (rich_text_field)
- published_date (date)
- author (metaobject_reference -> Author)
- featured_image (file_reference)

With this structure, multiple articles can reference the same author. When you update the author's bio, it's reflected everywhere.

Rendering Related Metaobjects

Liquid: Render Article with Author {%- assign article = shop.metaobjects.article['how-to-optimize-shopify'] -%} <article> <h1>{{ article.title.value }}</h1> <time>{{ article.published_date.value | date: "%B %d, %Y" }}</time> {%- assign author = article.author.value -%} {%- if author -%} <div class="author-box"> {%- if author.photo.value -%} {{ author.photo.value | image_url: width: 100 | image_tag: class: 'author-photo' }} {%- endif -%} <p>Written by <strong>{{ author.name.value }}</strong></p> <p class="author-bio">{{ author.bio.value }}</p> </div> {%- endif -%} <div class="article-content"> {{ article.content.value }} </div> </article>

Many-to-Many Relationships

Use list.metaobject_reference for many-to-many:

  • Product has metafield: custom.ingredients (list.metaobject_reference)
  • Ingredient metaobject can be referenced by many products
  • Great for: ingredient databases, certifications, related products

9. Real-World Use Cases with Code Examples

Use Case 1: Size Guide System

Problem: Fashion brand has 200 products across 10 categories, each needing size guidance. Copying size info to each product is error-prone and time-consuming.

Solution: Create a "Size Guide" metaobject with title, description, chart image, and measurement JSON. Create 10 entries (one per category). Add a custom.size_guide metafield (metaobject_reference) to products. Now, updating "T-Shirt Size Guide" updates all 50 T-shirt products instantly.

Use Case 2: Store Locator

Problem: Retail brand with 50 physical locations needs a store finder page. Third-party apps cost $30-$100/month.

Solution: Create "Store Location" metaobject with: name, address, city, state, zip, country, latitude, longitude, phone, hours (json), photo. Create 50 entries. Build a custom page template that loops through locations, renders a list, and optionally integrates with Mapbox or Google Maps using the coordinates.

Cost saved: $360-$1,200/year in app fees.

Use Case 3: Team/About Us Page

Problem: Company wants a dynamic "Meet the Team" page where non-technical HR can update team member profiles.

Solution: Create "Team Member" metaobject with: name, role, bio, photo, email, linkedin_url, order (integer for sorting). HR adds/removes team members via admin. Theme loops through entries sorted by order field.

Use Case 4: Product Certifications

Problem: Sustainable brand wants to display certification badges (Organic, Fair Trade, B Corp) on qualifying products. Certifications should link to info pages.

Solution: Create "Certification" metaobject with: name, badge_image, info_url, description. Create entries for each certification. Add custom.certifications (list.metaobject_reference) metafield to products. PDP renders badges with links.

Use Case 5: Product Ingredients/Materials Database

Problem: Skincare brand needs to list ingredients with detailed info (benefits, sourcing, allergens). Same ingredient appears in many products.

Solution: Create "Ingredient" metaobject with: name, description, benefits, sourcing, icon, allergen_warning. Products reference ingredients via list metafield. PDP shows ingredient list with expandable details pulled from metaobjects.

10. Schema Design Patterns and Best Practices

Pattern 1: The Reusable Content Block

Create metaobjects for content that appears in multiple places: announcements, promotional banners, FAQ sets. Reference them from pages, products, or theme sections.

Pattern 2: The Reference Hub

Create a central metaobject that many others reference. Example: "Brand" metaobject referenced by products, collections, and articles. Update brand info once, reflected everywhere.

Pattern 3: The Configuration Object

Store global settings that merchants can change without touching theme code. Example: "Homepage Config" metaobject with: hero_heading, hero_image, featured_collection, promo_text. Access via shop.metaobjects.homepage_config['settings'].

Best Practices

  1. Prefix types logically: content_size_guide, config_homepage for organization.
  2. Use handles consistently: kebab-case handles match URL conventions.
  3. Document your schema: Keep a reference doc of what each metaobject type does and its field definitions.
  4. Validate inputs: Use field validations (min/max length, file types) to prevent garbage data.
  5. Plan for translation: If you're on Shopify Markets, consider how metaobject content will be translated.

11. Performance Considerations

Liquid Performance

Metaobject Liquid queries are efficient but not free. Tips:

  • Avoid deep nesting: Accessing a metaobject that references another metaobject that references another adds overhead.
  • Limit loop sizes: Don't loop through 500 store locations on page load. Paginate or lazy-load.
  • Use fragment caching: If your theme supports it, cache metaobject-rendered sections.

Storefront API Performance

When using Storefront API:

  • Request only needed fields: Don't query all fields if you only need title and handle.
  • Use cursor-based pagination: For large lists, fetch in batches.
  • Cache responses: Metaobject content typically doesn't change often—cache aggressively.

Entry Limits

As of 2026, Shopify allows thousands of metaobject entries per type. However, very large datasets (10,000+ entries) may require pagination and filtering strategies.

12. Limitations and Workarounds

Current Limitations

  1. No Built-in Search: You can't search metaobject entries in Liquid. Workaround: Use JavaScript filtering or Storefront API with fetch.
  2. No Automatic Slugification: Handles must be manually set or programmatically generated.
  3. Translation Complexity: Multi-language stores need Translate & Adapt app or API-based translation workflows.
  4. No Versioning: Unlike products, there's no revision history for metaobject edits.
  5. No Scheduling: You can't schedule metaobject publishes. Workaround: Use a date field and filter in Liquid.

Workarounds

For Search: Create a JavaScript-powered search that queries Storefront API client-side, or pre-render a search index at build time (for headless).

For Scheduling: Add a publish_date field. In Liquid, wrap content in a conditional: if metaobject.publish_date <= 'now'.

13. Migrating from Apps to Native Metaobjects

If you're currently using a CMS app (Accentuate Custom Fields, Metafields Guru, Sanity, Contentful), you can migrate to native Metaobjects:

Migration Steps

  1. Inventory Current Data: Export all custom content from your current app.
  2. Design Metaobject Schemas: Create equivalent metaobject definitions in Shopify.
  3. Script the Migration: Use Admin API to bulk-create metaobject entries from exported data.
  4. Update Liquid Templates: Change references from app-specific syntax to native Liquid metaobject access.
  5. Test Thoroughly: Verify all pages render correctly.
  6. Decommission App: Once stable, uninstall the old app.

Migration Script Template (Node.js)

Node.js: Bulk Create Metaobjects const Shopify = require('@shopify/shopify-api'); async function migrateContentToMetaobjects(client, data) { for (const item of data) { const mutation = ` mutation { metaobjectCreate(metaobject: { type: "size_guide" handle: "${item.slug}" fields: [ { key: "title", value: "${item.title}" } { key: "description", value: "${item.description.replace(/"/g, '\\"')}" } ] }) { metaobject { id } userErrors { field message } } } `; const response = await client.query({ data: mutation }); if (response.body.data.metaobjectCreate.userErrors.length) { console.error('Error:', response.body.data.metaobjectCreate.userErrors); } else { console.log(`Created: ${item.slug}`); } } }

14. Frequently Asked Questions (15+ FAQs)

What plans support Metaobjects?

All Shopify plans support Metaobjects, including Basic. This is a core platform feature, not a Plus-exclusive.

Are Metaobjects free?

Yes. Unlike third-party CMS apps, Metaobjects are included in your Shopify subscription at no extra cost.

Can customers see Metaobjects in the admin?

No. Only staff accounts with appropriate permissions can view/edit metaobjects in the admin. Customers only see rendered content on the storefront.

How many Metaobject types can I create?

There's no strict limit on the number of definitions. Practically, you'll have dozens at most for a complex store.

How many entries can I have per type?

Thousands per type. Very large stores may have 10,000+ entries for types like "Store Location" or "FAQ".

Can I reference Metaobjects from products?

Yes. Add a metafield of type metaobject_reference to products. This links the product to a metaobject entry.

Can Metaobjects reference other Metaobjects?

Yes. A field of type metaobject_reference can point to entries of another (or the same) type. This enables hierarchies and relationships.

Are Metaobjects available in Storefront API?

Yes, but you must enable Storefront access when creating the definition. Toggle "Storefront: Active" in the admin or set access.storefront: ACTIVE via API.

Can I use Metaobjects with Headless (Hydrogen)?

Absolutely. Query metaobjects via Storefront API in your Hydrogen loaders. It's the recommended approach for dynamic content.

How do I translate Metaobject content?

Use Shopify's Translate & Adapt app or the Translation API. Metaobject fields are translatable just like product fields.

Can I filter/search Metaobjects in Liquid?

Basic filtering (like checking a boolean field) works in Liquid loops. For full-text search, use JavaScript with Storefront API client-side.

What happens if I delete a Metaobject that's referenced?

References become null. Your Liquid code should handle nil values gracefully to avoid errors.

Can I bulk import Metaobjects via CSV?

Not via native UI. Use the Admin API with a script for bulk imports. Shopify's Matrixify app also supports metaobject import/export.

Are Metaobjects included in theme backups/exports?

No. Metaobjects are store-level data, not theme data. Theme exports include only code. Export metaobjects separately via API.

Can staff with limited permissions edit Metaobjects?

Yes. You can grant "Metaobjects" permission to staff accounts, allowing content editors to update metaobjects without full admin access.

15. Conclusion and Next Steps

Shopify Metaobjects unlock a level of content flexibility that previously required expensive third-party apps or custom backends. By understanding when to use Metaobjects vs. Metafields, designing thoughtful schemas, and leveraging relationships between content types, you can build sophisticated commerce experiences entirely within Shopify's ecosystem.

The benefits compound over time: content is easier to manage, updates are reflected instantly across all referencing products, and you're not locked into a third-party app's pricing or roadmap.

Your Action Plan

  1. Identify content pain points: What content do you duplicate across products? What requires app workarounds?
  2. Design your Metaobject schema: Start with one type (like Size Guides). Define fields thoughtfully.
  3. Create entries: Populate with real content. Get feedback from the team who will maintain it.
  4. Integrate into theme: Update Liquid templates to render metaobject data.
  5. Extend progressively: Once comfortable, add more metaobject types (Team, Locations, FAQs, etc.).
  6. Retire apps: If Metaobjects replaces what an app was doing, uninstall and save on monthly fees.

Need Help Implementing Metaobjects?

Whether you need to design a metaobject architecture, migrate from a CMS app, or integrate metaobjects into a custom theme, I can help. I've implemented metaobject systems for fashion, beauty, home goods, and B2B brands on Shopify.

Request Implementation Help