Shopify Metafields: The Complete Guide for Merchants and Developers

Shopify metafields are custom data fields you attach to existing store resources (products, variants, collections, orders, customers) to store information Shopify's default schema does not capture. Every Online Store 2.0 theme can surface those fields as dynamic sources with zero code edits. If you have ever needed to display a fabric composition, a burn time, a warranty period, or a regulatory ingredient list on a product page, metafields are the right tool.

Key takeaways

• Metafields attach extra data to an existing Shopify resource; metaobjects are standalone, reusable records referenced from many places.
• Shopify API version 2026-04 added automatic cart-to-order metafield propagation, removing the biggest gap in custom checkout data flows.
• The per-metafield value cap dropped from 2 MB to 16 KB in April 2026, which means anything larger must move to metaobjects or the Files API.
• Platform limits now stand at 256 app definitions, 256 merchant definitions, and 1 million entries per definition.
• The article_reference type (added in the 2025-10 API release) lets you link products directly to blog posts for content-driven SEO.

What exactly is a Shopify metafield?

A metafield is a structured key-value pair that lives on a Shopify resource. Every metafield has four required attributes:

• Namespace, a logical container, e.g. custom or my_app
• Key, the field identifier within that namespace, e.g. fabric_type
• Type, the data type (text, number, boolean, file reference, JSON, etc.)
• Value, the actual data you are storing

The combination of namespace and key must be unique per resource. Shopify uses namespaces to prevent collisions between app-owned fields and merchant-owned fields.

In Liquid, you access a product metafield with:

{{ product.metafields.custom.fabric_type.value }}

For rich-text fields, use the metafield_tag filter to render HTML output correctly:

{{ product.metafields.custom.care_instructions | metafield_tag }}

Supported metafield types

Shopify supports a broad set of content types. The most commonly used are:

The article_reference and list.article_reference types, added in the 2025-10 API update, give you a native way to link products to editorial content, which is a clean win for content-driven SEO strategies.

Metafields vs. metaobjects: the decision you need to get right

This is the most common architecture mistake I see on client stores. The rule is simple:

Use a metafield when the data is unique to one specific resource and has no reuse value.

Use a metaobject when the same structured record appears across many resources or needs to be edited in one place and reflected everywhere.

A real example: one wholesale apparel merchant pasted the same 18-row size chart into 247 individual product metafields. When the size standard changed, 246 product pages went stale while one was updated. Migrating that data to a single metaobject took 90 minutes. Now every product page that references it updates on the next request from a single edit.

Metaobjects were introduced in February 2023 and are available on every Shopify plan with no plan-gating. Think of a metaobject definition as a database table schema, and each entry as a row. A Size_Guide definition might have fields for title, image, and a measurements table. You create entries (T-Shirt Size Guide, Jeans Size Guide) and reference them from as many products as needed.

Quick decision matrix:

• Product-specific copy a merchant edits per SKU? Metafield.
• Size chart shared across 50+ apparel SKUs? Metaobject.
• Seasonal shipping deadline that varies per product? Metafield.
• Authorized reseller list (name, region, URL) used site-wide? Metaobject.
• Team member record referenced from About, Careers, and blog posts? Metaobject.

The 16 KB limit change you cannot ignore (April 2026)

This is the single most disruptive metafield change of recent years. Shopify reduced the per-metafield value ceiling from 2 MB down to 16 KB, a 99.2% reduction, which took effect in April 2026. The stated rationale is database infrastructure cost and performance.

What this means practically:

• JSON metafields used as mini-databases (common in older app integrations) are now broken or silently truncated if they exceed 16 KB.
• Large rich-text blocks or embedded base64 images stored in metafields must move to the Files API or be restructured as metaobjects.
• New implementations should be designed with 16 KB as the ceiling from day one, leaning on metaobjects, references, and the Files API for anything heavier.

If you are unsure whether your store is affected, audit your metafields via the Admin GraphQL API, querying the value field length before any migration.

The 2026-04 API update: cart metafields now carry to orders

This is the biggest developer-facing metafield news of 2026. Shopify API version 2026-04 introduced automatic propagation of cart metafields into order metafields when specific conditions are met.

The practical requirement: the namespace and key must match exactly between the cart-side and order-side metafield definitions, and the cartToOrderCopyable capability must be enabled on the order metafield definition.

Why this matters for merchants: stores that collect custom data at checkout (personalization tokens, gift message flags, loyalty metadata, third-party shipping instructions) previously had to rely on cart attributes or custom checkout scripts to keep that data visible on the resulting order. That fragmented approach is now replaced by a unified metafield model with explicit permissions and namespace controls. The result is cleaner access controls for apps, fewer edge cases during checkout, and a more predictable data pipeline for fulfillment and reporting workflows.

If you use ETL pipelines to export orders for finance or ERP reconciliation, update your field mappings to include the relevant order metafield values.

How to create metafield definitions (no code required)

1. Go to Shopify Admin > Settings > Custom data.
2. Choose the resource type (Products, Variants, Collections, Customers, Orders, etc.).
3. Click Add definition.
4. Enter a name, namespace, key, and select the content type.
5. Add optional validations (character limits, URL format, numeric ranges).
6. Save.

Once a definition exists, any Online Store 2.0 theme section that supports dynamic sources will expose it as a selectable field in the theme editor, no Liquid editing needed.

For bulk population, Shopify's native CSV import handles a limited set of metafield columns. For full control, Matrixify is the de facto tool: it maps CSV columns directly to namespace-key pairs and validates types during import.

Rendering metafields in your theme

Dynamic sources (no-code path)

In the theme editor, click any text, image, or media block in an OS 2.0 section, then click the Connect dynamic source icon (the database icon). Your defined metafields appear as options. This is the right path for content editors who should not be touching code.

Liquid (code path)

For custom sections or conditional logic, write it directly in Liquid:

{% if product.metafields.custom.is_hazardous.value %}
  <p class="hazard-notice">⚠ Handle with care. See safety sheet.</p>
{% endif %}

{% assign warranty = product.metafields.custom.warranty_years.value %}
{% if warranty %}
  <p>{{ warranty }}-year warranty included.</p>
{% endif %}

Shopify Flow (automation path)

Since April 2024, Shopify Flow can read typed metafields directly. You select a resource, choose a metafield from the known definitions list, and Flow generates an alias you use in subsequent steps. This is useful for automating tagging, notifications, or fulfillment routing based on metafield values, without custom apps.

Metafields for SEO: the article_reference opportunity

Content-driven SEO is one of the highest-ROI uses of metafields right now. With the article_reference type available since the 2025-10 API, you can link a product directly to a specific blog post from within the product metafield definition. The blog post URL becomes a structured reference rather than a hardcoded string, which means it survives handle changes and does not require manual updates across hundreds of products.

This matters for SEO because it creates a navigable internal link structure that crawlers can follow, and it keeps the supporting editorial content contextually close to the transactional page. For stores with a large library of buying guides or how-to articles, this is worth implementing systematically across your catalog.

For a broader look at how structured data and content organization affect your store's search visibility, see our Shopify SEO services and Shopify theme development pages.

Platform limits at a glance (current as of mid-2026)

Common mistakes to avoid

• Storing large JSON blobs in a single metafield. Since April 2026 the ceiling is 16 KB. Use metaobjects or break the data into smaller typed fields.
• Duplicating shared data across thousands of products. If the same value appears on more than a handful of products, it belongs in a metaobject.
• Renaming metafields in production while the theme references them. Update theme references first, then rename the definition. Reversing that order breaks live storefront output.
• Skipping definitions and using raw namespace-key pairs. Without a definition, you lose type validation, dynamic source support in the theme editor, and clean admin UI display.
• Using the global namespace. Apps previously used global.title and similar patterns. That namespace is reserved and its behavior is inconsistent across API versions. Use a custom namespace.
• Not auditing legacy app metafields. Older apps leave behind orphaned metafields under namespaces like namespace_1 or apps.my_old_app. These count against your definition limits and pollute the admin UI.