Shopify Metafields Complete Guide

By Kokil Thapa | Last reviewed: September 2026

Shopify metafields let you attach structured custom data to products, collections, customers, and other core objects without hacking the database. If you are building a theme, a custom app, or migrating from WooCommerce, this Shopify Metafields Complete Guide walks through definitions, types, Admin API calls, and Liquid rendering the way you would on a live store. I have used metafields on florist and multi-currency Shopify eCommerce builds where standard product fields could not hold care instructions, delivery zones, or B2B price tiers. The pattern is simple once you separate definitions from values.

What Are Shopify Metafields and Why Do Stores Need Them?

Every Shopify resource—product, variant, collection, customer, order, shop, page, blog, article—can carry extra metadata outside the built-in schema. Metafields solve problems native fields cannot: ingredient lists, size charts, warranty PDFs, SEO overrides, or Nepal-specific attributes like VAT notes and delivery ward codes.

Before Shopify shipped metafield definitions, merchants typed free-form keys in Admin. That led to typos, inconsistent namespaces, and broken theme logic. Definitions now enforce type, validation, and Admin UI rendering. Treat metafields as part of your data model, not a dumping ground.

Common use cases I see on eCommerce development projects include:

• Product specs (material, dimensions, care instructions) for filtered search
• Collection hero copy and banner images beyond the default description field
• Customer loyalty tier or wholesale account flags for B2B pricing rules
• Page-level FAQ blocks and structured content for programmatic SEO
• Order-level fulfilment notes synced from an ERP or warehouse system

Metafields do not replace a full PIM or CMS. They excel when Shopify remains the commerce source of truth and you need a dozen to a few hundred typed fields—not thousands of relational tables.

How Do You Create and Manage Metafield Definitions in Shopify Admin?

Definitions tell Shopify what type of data you expect and how to show it in Admin. Without a definition, a metafield still works in Liquid, but merchants get a raw key-value editor that invites mistakes.

Step-by-step in Shopify Admin (2026)

1. Open Settings → Custom data in your Shopify admin.
2. Choose the resource (Products, Variants, Collections, Customers, etc.).
3. Click Add definition and set namespace, key, name, and type.
4. Optionally pin the field to the resource detail page and set validation rules.
5. Save, then open any product and fill the new field under the metafields section.

Pick namespaces deliberately. I standardise on custom for merchant-facing fields and app-specific namespaces like my_app for integration data. Never reuse the same key with different types across environments.

Namespace and key naming rules

Shopify allows letters, numbers, underscores, and hyphens. Keys are unique per namespace on a given resource. A practical pattern:

namespace: custom
key: care_instructions
type: multi_line_text_field

namespace: custom
key: size_chart_page
type: page_reference

namespace: shipping
key: delivery_zone_kathmandu
type: single_line_text_field

Document every namespace.key in your theme README or internal wiki. Future you—and the next developer—will need that map when debugging empty Liquid output.

What Metafield Types Should You Choose for Products and Pages?

Shopify supports scalar types (text, number, boolean, date, JSON), reference types (product, variant, collection, page, file), and list variants of most scalars. Type choice affects Admin UX, API validation, and how Liquid renders the value.

For Nepali storefronts selling physical goods, I often pair a multi_line_text_field for Nepali care copy with a single_line_text_field English summary. That keeps Unicode content manageable while preserving a shorter field for Google Merchant feeds.

How Do You Create Metafields with the Shopify Admin API?

For migrations, ERP sync, or custom apps, the GraphQL Admin API is the reliable path. Use API version 2026-07 or later so metafield definition mutations match current Shopify behaviour. REST metafield endpoints still exist, but GraphQL gives you typed definitions and bulk operations in one request.

Create a metafield definition via GraphQL

mutation CreateProductMetafieldDefinition {
  metafieldDefinitionCreate(
    definition: {
      name: "Care instructions"
      namespace: "custom"
      key: "care_instructions"
      type: "multi_line_text_field"
      ownerType: PRODUCT
      access: {
        admin: MERCHANT_READ_WRITE
        storefront: PUBLIC_READ
      }
    }
  ) {
    createdDefinition {
      id
      name
      namespace
      key
    }
    userErrors {
      field
      message
    }
  }
}

Set storefront: PUBLIC_READ when your Online Store 2.0 theme or headless Storefront API frontend must read the field. Keep integration-only fields private to avoid leaking wholesale cost data.

Set a value on one product

mutation SetProductMetafield($ownerId: ID!, $value: String!) {
  metafieldsSet(metafields: [{
    ownerId: $ownerId
    namespace: "custom"
    key: "care_instructions"
    type: "multi_line_text_field"
    value: $value
  }]) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

Pass the product GID as ownerId, for example gid://shopify/Product/1234567890. Bulk imports should use bulkOperationRunMutation when you are updating thousands of SKUs from a CSV export.

Rate limits and idempotency

Admin API calls cost points based on query complexity. Batch metafield writes inside a single metafieldsSet call when possible. On a real client project syncing daily inventory, I store the last successful sync timestamp in a shop metafield so retries skip unchanged rows.

Official reference: see Shopify’s metafields documentation and the Admin GraphQL API 2026-07 for current mutation names and access scopes (write_products, write_customers, etc.).

How Do You Output Metafields in Liquid Themes?

Online Store 2.0 themes read metafields through the resource object. Syntax follows resource.metafields.namespace.key. Dynamic sources in the theme editor can bind section settings directly to metafields—no hard-coded keys in JSON templates if you prefer merchant control.

Basic Liquid examples

{% assign care = product.metafields.custom.care_instructions %}
{% if care != blank %}
  <div class="product-care">
    <h3>Care instructions</h3>
    {{ care | metafield_tag }}
  </div>
{% endif %}

{% assign size_chart = product.metafields.custom.size_chart_page.value %}
{% if size_chart %}
  <a href="{{ size_chart.url }}">View size chart</a>
{% endif %}

The metafield_tag filter renders type-aware HTML for many field types. For rich text, it saves you from hand-parsing JSON. For plain strings, escape user content unless you fully trust the source.

Theme blocks and JSON templates

In a section schema, enable metafield pickers:

{
  "type": "text",
  "id": "subtitle",
  "label": "Product subtitle",
  "info": "Or bind a dynamic source to custom.subtitle metafield"
}

Merchants then connect dynamic sources in the theme customizer. Developers ship the section; merchandisers map fields without redeploying code. That split works well on WooCommerce-to-Shopify migrations where florists want editable petal-care notes per SKU.

Deeper Liquid patterns live in the Shopify custom theme development guide. Pair metafield-driven tabs with lazy-loaded images so Core Web Vitals stay within target on mobile Nepal networks.

What Are Common Shopify Metafield Mistakes and How Do You Fix Them?

Most production bugs are boring: wrong namespace, missing storefront access, or Liquid assuming a value exists on every variant. The fix is usually documentation and defensive templates—not another app.

Mistake 1: Skipping definitions before bulk import

CSV importers and custom scripts can write raw metafields fast. Without definitions, types drift ("12" as string vs integer) and Admin shows unreadable JSON. Create definitions first, then import values that pass validation.

Mistake 2: Forgetting storefront visibility

A metafield visible in Admin but hidden from Storefront returns blank in Liquid on the live theme. Re-check the definition access block after cloning stores from staging to production.

Mistake 3: Using metafields as a relational database

Storing huge JSON graphs or duplicating entire product catalogs inside one json metafield breaks down quickly. Use product references and metaobjects for structured entities. Metaobjects behave like custom content types with their own entries—ideal for store locators, author profiles, or certificate blocks on legal content sites.

Mistake 4: SEO duplication

Do not mirror the product description into a metafield and output both on the page. Pick one canonical body field. Use metafields for supplementary specs and JSON-LD helpers. Coordinate with your technical SEO process so structured data pulls from the same source Google Merchant Center expects.

When debugging, use GraphiQL or the JSON formatter tool to inspect metafield payloads returned from the Admin API. Compare staging and production GIDs carefully—IDs differ even when handles match.

How Do Metafields Compare to Metaobjects and Standard Fields?

Choosing between platforms? The Magento 2 vs Shopify vs WooCommerce comparison covers where metafields fit Shopify’s lighter custom-data model versus EAV-heavy Magento attributes or WordPress post meta.

For custom apps that write metafields at scale, follow the same auth and webhook patterns described in the Shopify Admin API development guide. If you outgrow Admin API throughput, queue writes and reconcile with a nightly full sync job.

Key Takeaways

• Create metafield definitions before bulk imports so types and Admin UI stay consistent across environments.
• Set storefront: PUBLIC_READ on any field your Liquid theme or headless storefront must render.
• Use namespace.key conventions (custom.care_instructions) and document them for merchants and developers.
• Guard every Liquid output with blank checks; use metafield_tag for type-safe rendering where available.
• Prefer metaobjects when you need reusable structured entries, not giant JSON blobs in a single metafield.
• Align metafield-driven content with SEO and feed strategy so you do not duplicate body copy Google already indexes.

People Also Ask

What is the difference between metafields and metaobjects in Shopify?

Metafields attach extra fields to an existing resource like a product or customer. Metaobjects are standalone structured records—think store locations or recipe cards—that you reference from metafields. Use metafields for per-SKU data; use metaobjects when the same structure repeats across many entries.

Can Shopify metafields be used for search and filtering?

Yes. List-type metafields and typed definitions power Shopify Search & Discovery filters when configured in Admin. Third-party search apps also index public metafields via the Storefront API. Keep facet values normalised—mixed spelling in a list field breaks filter UX.

Do metafields work with Shopify Markets and B2B?

Metafields are store-scoped unless your integration copies them per market catalog. For B2B price lists, combine customer metafields with Shopify B2B company locations rather than storing prices in unsecured product metafields visible on Storefront.

How many metafields can a Shopify product have?

Shopify enforces per-resource limits that change over time; check current platform limits in Shopify Help before architecting hundreds of keys per SKU. In practice, stay well below the cap—group related data into metaobjects or JSON only when the shape is truly nested.

Build Custom Data Models on Shopify With Confidence

Metafields are the cleanest way to extend Shopify products and pages without fighting the core schema. This Shopify Metafields Complete Guide gives you the definition-first workflow, API mutations for Admin API 2026-07, and Liquid patterns that survive merchant edits and theme updates. Start with a short namespace map, expose only what the storefront needs, and validate before you import ten thousand rows from a legacy catalog.

Need help mapping metafields for a migration, custom theme, or ERP sync on a Nepal or international store? Review our eCommerce development services, browse the Nepal Gift Card and Petals Agro Nepal portfolio work, or contact us to plan your custom data layer before go-live.