Skip to content
Organized product data library with structured fields, reusable content, and product attributes for Shopify
ShopifyOct 4, 202616 min

Shopify Metafields and Metaobjects: Custom Data Without a Rebuild

Shopify stores custom data in two structures, and both live in the admin rather than in your theme. Metafields extend an existing platform data model (opens in new tab), such as products, customers and orders, with your own custom data. Metaobjects let you create an object with multiple fields when the data is best represented by multiple fields.

Because the data sits outside the theme, it survives a theme change. You can add metaobject entries to multiple areas of your theme, and add them to a new theme without recreating the data (opens in new tab). Most of what a brand wants to add to a product page, such as care instructions, materials, size guides and ingredient lists, fits that model.

We build Shopify themes and model custom data for the brands we work with. This is the breakdown we’d give a client deciding what to configure in the admin and what to scope as theme or app work. It reflects the Shopify metafields limits that changed in October 2025 and the reporting changes of 2026.

What Shopify Metafields and Metaobjects Are

What is a metafield in Shopify? It’s an extra field on a resource Shopify already has. Metafields are key-value pairs (opens in new tab) made of an identifier (a namespace plus a key), a value and a type. A product’s fabric weight, a customer’s loyalty tier and an order’s gift note are all metafields on existing records.

A metaobject is a record type you define yourself. In database terms (opens in new tab), a metafield definition is a new column on a built-in table, a metaobject definition is a custom table, and a metaobject entry is a row. Examples of metaobjects are a product highlight, an influencer profile, an FAQ and an event appearance.

A metaobject has two parts in the admin. The definition, the group of fields that sets the structure, is managed under Settings (opens in new tab), and entries are created under Content > Metaobjects. When a published entry is edited, the edit is reflected wherever that entry is used (opens in new tab).

When to Use a Metafield and When to Use a Metaobject

Use a metafield when the data describes something Shopify already has (opens in new tab), such as a product, order or customer, and a metaobject when the data doesn’t belong to an existing object. Most apps use both, with a metaobject defining the record and a metafield attaching it to the products it applies to.

That pairing covers most product page cases. A designer bio that appears on dozens of products is one metaobject entry and a metaobject reference metafield on each product, so the bio gets edited once. A wash temperature that belongs to one product is a plain metafield.

  • Use a metafield when the value belongs to one record and has one part: a subtitle, a care note, a material.
  • Use a metaobject when the data has several fields and gets reused: a size chart, an ingredient, a designer, a store location.
  • Use a metaobject reference metafield to attach those reusable records to the products, collections or customers they apply to.

Don’t build relationships by storing handles or IDs in plain text fields (single_line_text_field). A reference type keeps the link intact, and a deleted product or variant is automatically removed from every list metafield that references it (opens in new tab). A handle typed into a text field gets no such cleanup.

Definitions for Shopify Metafields: Types, Namespaces and Keys

A definition is the schema for a metafield. It has a name, a namespace and key (opens in new tab), an optional description, a type, optional validations and options. The namespace and key are separated by a period and can contain only letters, numbers, underscores and hyphens, as in custom.color.

The namespace groups related fields. Grouping metafields within a namespace keeps them from conflicting with other metafields that have the same key name (opens in new tab). The namespace also signals ownership: app-owned metafields use a reserved app namespace (opens in new tab) and merchant-owned ones can use any namespace that isn’t reserved, such as custom.

The type decides what the value can hold and where it can be used. Types fall into seven categories (opens in new tab): date and time, measurement, number, text, reference, other and advanced. Those seven categories hold 57 content types, and developers get 113 type identifiers (opens in new tab) because every list form is listed separately. Metaobjects use the same data types.

A metafield can exist without a definition, and Shopify calls that an unstructured metafield. Without a definition, a metafield is an untyped string that can’t be edited in the Shopify admin or validated (opens in new tab). Unstructured metafields are typically made by an app.

Shopify also ships standard definitions with reserved namespaces and keys, such as descriptors.care_guide and reviews.rating. There are 16 of them (opens in new tab), including product subtitle, care guide, ISBN, related products and complementary products. Shopify recommends using a standard definition whenever possible (opens in new tab).

What's Fixed Once a Definition Exists

The name, description, validations and access permissions (opens in new tab) of a definition can be updated. The namespace and key are immutable, and the owner type can’t be migrated. Changing the type is possible only with caveats, including values that become invalid, so plan as if the type is fixed.

Validations can be tightened later, but the change may fail if existing metafields violate the new constraint. If some values are invalid, you can’t use the metafield until every error is fixed (opens in new tab). For metaobjects, type identifiers can’t be changed after creation (opens in new tab), so plan them carefully.

Deletion is permanent. Deleting metafields that are connected to your theme can cause display errors (opens in new tab) for customers visiting your online store. Deleting a metaobject definition deletes all of its entries (opens in new tab).

Adding a definition over existing unstructured data carries its own risk. Only create a definition for metafields whose namespace and key you recognize (opens in new tab), because a definition placed on metafields an app depends on might stop that app from working as expected.

The Current Limits on Shopify Metafields and Metaobjects

On October 24, 2025, Shopify announced higher limits for both structures (opens in new tab). Metaobject entries now have a 1,000,000 entry limit per definition, which replaces the previous plan-based restrictions of 64,000 (non-Plus) and 128,000 (Plus). The entry limit no longer depends on your plan.

Metaobject definitions still do. Merchants get 128 metaobject definitions on the Basic, Shopify and Advanced plans (opens in new tab) and 256 on Plus and Enterprise. Each definition can have up to 40 fields and up to 1,000,000 entries, and standard metaobject definitions don’t count toward the total.

For Shopify metafields, merchants can create up to 256 metafield definitions per resource type (opens in new tab). Products, variants, customers and orders each get their own 256. Each installed app gets its own 256 metafield definitions per resource type, and apps aren’t competing with each other for definition space. You can have up to 256 metafield definitions for each type (opens in new tab), such as products or customers.

Value size is capped per metafield. Most types are capped at 64KB, JSON at 128KB, and the id and url types at 2KB. A list holds up to 128 items, except lists of metaobject references, which hold up to 1024, and a single line text definition with preset choices is limited to 128 choices.

Limit What it applies to Number
Metafield definitions Merchant-created, per resource type 256
Metaobject definitions Merchant-created, Basic, Shopify and Advanced plans 128
Metaobject definitions Merchant-created, Plus and Enterprise plans 256
Fields Per metaobject definition 40
Entries Per metaobject definition 1,000,000
Value size Most metafield types 64KB
Value size JSON metafields 128KB
List length Items in a list metafield 128
List length Items in a list of metaobject references 1024
Pinned definitions Per resource type 50

Pinning controls which fields show on a record in the admin. Only pinned metafields display automatically, and you can pin up to 50 definitions (opens in new tab) for each part of your store. A catalog with more than 50 product metafield definitions will have some that staff need to open from the full list.

Several features carry a separate, smaller ceiling. Only 128 definitions can power smart collections, 50 can act as admin filters on products, and 5 on orders. A store can reach one of these long before it reaches 256 definitions.

Product Metafields and Category Metafields in Shopify

Product metafields in Shopify come from three places: standard definitions, custom definitions you create, and category metafields. Category metafields map to specific product categories (opens in new tab) in Shopify’s Standard Product Taxonomy, a predefined, standardized list (opens in new tab) of categories, attributes and attribute values for products.

Assigning a category is what makes the attributes available. The Shirts category (opens in new tab), for example, makes available category metafields for size, neckline, sleeve length type, top length type, age group, fabric, target gender, clothing features and color. Category metafields use metaobjects and metaobject entries for their values, and some are added by default based on AI predictions.

Custom product metafields can join that card. You can assign one or more categories to your custom product metafields (opens in new tab), after which they display in the Category Metafields card on the product page. That lets a brand-specific field, such as a fit note, appear only on products in the categories where it applies.

The taxonomy’s own attributes are fixed. The Standard Product Taxonomy doesn’t currently support custom attributes, and the standard metaobject definitions behind those attributes can’t be modified (opens in new tab). Entries are editable, and edits to an existing entry update everywhere that entry is connected.

Category metafields can also drive variants. You can connect a variant option (opens in new tab) to a category or product metafield of the metaobject reference list type. Color entries used as variant options can display as swatches on storefront product pages.

Getting Shopify Metafields and Metaobjects Onto the Storefront

A field in the admin does nothing for a shopper until a template renders it. There are two no-code routes: dynamic sources in the theme editor, and page templates generated from metaobject entries. Which product page content earns a place is a separate question from how to store it, and our guide to five product page tests covers which changes to test first.

Connecting Shopify Metafields With Dynamic Sources in the Theme Editor

You connect metafields to your theme by adding sections or blocks that support dynamic sources (opens in new tab). The theme has to cooperate, because not all sections or blocks support them (opens in new tab).

The connection is made once per template, not once per product. The section isn’t filled in for products without a value (opens in new tab) for that metafield, so you can set up a single product template that works for all your products. One template can therefore serve a catalog where only some products have a care guide.

Which metafield fits which setting is a type question. A text setting (opens in new tab) accepts single line text and lists of it, integers, decimals, dates, date and time values, weights, volumes, dimensions, ratings and money. A rich text setting accepts those plus multi-line text, rich text and links, an image picker accepts a file reference, and metaobject settings accept metaobject references.

Connections are capped at 100 dynamic sources in a JSON template and 50 in a single setting.

Metaobjects connect at the block level. Connecting a metaobject to a block (opens in new tab) automatically maps compatible fields to the block’s settings, and a list field adds each entry in the list to the block setting. The metaobject needs Storefronts access to display on your online store.

Metaobject Page Templates

Metaobject entries can render as web pages. You can use metaobjects to build repeatable landing pages (opens in new tab) for your online store in three steps: create a definition with storefront access, create entries, and create a metaobject template. The option to publish entries as web pages (opens in new tab) needs Storefront access selected.

One template serves every entry. The first template created for a metaobject (opens in new tab) must be the default and is used automatically by all active entries for that definition. A designer directory, a store locator or an ingredient glossary becomes one template and as many entries as you need.

Those pages can carry SEO fields. The renderable capability (opens in new tab) exposes metaobject SEO fields to Liquid and the Storefront API, and metaobjects with it are included in the store’s sitemap. Entries in draft status aren’t served: a draft entry under a publishable definition returns nil (opens in new tab).

Where Else Shopify Metafields Are Read

Shopify metafields are read by more than the theme. The same values are available to themes (opens in new tab), Shopify Functions, checkout and admin extensions, Shopify Analytics and the admin.

In Liquid, the metafield syntax (opens in new tab) is {{ resource.metafields.namespace.key }}, and you can’t create metafields in Liquid. Metaobjects are read (opens in new tab) as {{ metaobjects.type.handle }}.

The storefront access setting (opens in new tab) on a metafield definition controls the Storefront API, which headless and custom storefronts use, and Liquid templates can read metafields regardless of it. Shopify describes the same option (opens in new tab) as allowing the metafield in the online store through Liquid or the Storefront API. By default, values for custom metafields aren’t accessible to custom storefronts (opens in new tab), so a headless build needs the option turned on for each custom definition it reads. Metaobjects follow a different rule: Shopify requires storefront access for a metaobject to display on the online store.

The Storefront API can’t write. You can’t create, update or delete metafields (opens in new tab) with it. Writes go through the GraphQL Admin API, where one metafieldsSet call is capped at 25 metafields and a 10MB payload.

Filtering through the Admin API needs a capability enabled on the definition. Shopify announced on July 24, 2026 that, starting in API version 2026-10, the GraphQL Admin API returns an error (opens in new tab) when a query filters by a metafield that isn’t set up for filtering, where it used to silently return incorrect results. Any integration that filters by metafield should be checked against that version.

Shopify Metafields in Flow, Functions and Checkout

Flow has actions that update metafields (opens in new tab) on collections, companies, company locations, customers, orders, products, product variants and the shop. You can create metafield definitions in a workflow with the Create metafield definition action. For metaobjects, the Get metaobject entries action (opens in new tab) returns up to 100 entries at a time, and querying by field value requires filtering to be enabled on the metaobject. Our guide to Shopify Flow automations covers the workflows these actions sit inside.

Shopify Functions read custom data through input queries. An input query can read metafields from products, customers, carts and more (opens in new tab), but metaobjects must be app-owned. Merchant-owned types (opens in new tab) don’t work in function input queries.

Size matters inside a function. Shopify Functions input queries don’t return metafield values larger than 10,000 bytes, and the function receives null for the value even though it’s still stored. A discount rule that reads a large JSON metafield can therefore get nothing back from a value the admin shows as present.

In checkout, the Metafields API for checkout UI extensions (opens in new tab) gives access to app-owned metafields and the ability to write cart metafields. Cart metafields copy to order metafields at order creation when a matching order definition has that capability enabled. Shopify announced on April 27, 2026 that checkout metafields were removed from checkout and customer account UI extensions (opens in new tab) as of API version 2026-04, and our post on checkout extensibility and Shopify Functions covers the extension model.

Filters, Collections, CSV and Bulk Editing

Storefront filters can run on custom data. Custom filters (opens in new tab) are based on the product options, metafields or metaobjects used in your store, and a metafield filter can use seven value types, among them single line text, decimal, integer, true or false and metaobject reference. A store is capped at 25 filters, each filter shows at most 100 values, and collections with more than 5,000 products don’t display filters.

Automated collections accept metafield conditions on a short list of types. The supported types (opens in new tab) are true or false, integer, decimal, rating and single line text, and a single collection is capped at 60 total conditions. A definition used as a condition can’t be deleted until the collection stops using it.

Bulk work splits by resource. You can edit metafields in bulk (opens in new tab) for products, variants, collections and customers. A defined product metafield is included in product CSV exports (opens in new tab), under a column header in the format <name> (product.metafields.<namespace>.<key>). Variant metafields aren’t supported for product CSV import or export.

Metafields and Metaobjects in Shopify Reports

On February 12, 2026, Shopify announced that you can group and filter by metafields (opens in new tab) on products, variants, customers and orders, for example by material, loyalty tier or ingredients, directly in Reports and Explore. A fabric metafield can now be a row in a sales report, with no export and spreadsheet join.

The feature is opt-in per definition. A custom metafield only becomes available as a report dimension or filter (opens in new tab) once its Filter or group data in Analytics option is turned on. A customer loyalty tier is one example of a metafield used to personalize the store experience, and our guide to ecommerce personalization on Shopify covers the on-site treatments Shopify supports natively.

Two more changes landed on September 28, 2026. If you attach a metaobject to a product, variant, customer or order through a metafield, its fields can now be used in Analytics (opens in new tab), and app-created metaobjects are excluded until Analytics is turned on for the definition, by you or by the app. Category metafields (opens in new tab) now show up as dimensions and filters next to custom metafields, with nothing to turn on if products are already categorized.

The reference type you pick affects reporting. With a mixed reference (opens in new tab), the metaobject’s fields can’t be used as dimensions or filters in reports. Not every metaobject field type can be used in reports, either.

Where Native Stops and Theme or App Work Begins

The stopping points below are the lines we’d check a requirements list against before quoting it as configuration.

Product reference lists. A “pairs well with” row driven by a list of products is a common request. Product reference lists need a custom section or a third-party theme that uses product list settings (opens in new tab).

Metaobject page templates. The template is empty (opens in new tab) when it’s first created in the Online Store editor, and you have to add sections to it to display content. If your theme’s sections don’t suit the fields in the entry, the page needs sections built for it.

Theme support and field types. Vintage themes, and metafield types a theme doesn’t support, need theme code edits (opens in new tab). A mixed reference (opens in new tab) needs developer support to be used on the storefront, JSON is a type for advanced use cases, and rich text connects only to theme settings built for rich text.

The home page and other non-product templates. On the home page you can connect metaobjects from Content > Metaobjects, but not metafields with metaobject references from your product metafields. Featuring a product’s referenced data outside a product template takes Liquid.

Variant data in bulk. The product CSV carries product metafields and not variant metafields. To edit variant metafields in bulk, you need to use the variant bulk editor and then add metafield columns.

Logic in Functions and checkout. Functions read metafields on products, customers and carts but only app-owned metaobjects, and they receive null for any value over 10,000 bytes. In checkout, a UI extension reads app-owned metafields and writes cart metafields. Both are code a developer writes and deploys.

Data an app created. When an app is uninstalled, Shopify deletes its app-owned metafield definitions (opens in new tab) and temporarily retains the metafields and their values without a definition. There’s no guarantee of how long Shopify retains them after an uninstall. Data that has to outlive an app belongs in a merchant-owned definition.

The JSON size cap. JSON values are held to 128KB and most other types to 64KB. A specification table or a long structured payload that exceeds that needs to be split across fields or moved into metaobject entries.

If your list includes custom sections, built-out metaobject templates or types the theme editor can’t connect, that’s theme development. BLKDG’s custom Shopify theme development team offers a free Growth Audit that looks at why you aren’t getting found or converting online and gives you a roadmap for fixing it.

Which Custom Data to Model With Shopify Metafields First

Start with the fields that pass three checks: the value belongs to a product or variant, its type is one that dynamic sources accept, and your theme has a block that accepts it. Those ship without code. Use a standard definition where one exists, since Shopify recommends it and standard metafield definitions don’t count toward limits unless specified.

Move repeated, multi-field content into Shopify metaobjects next, and attach it with metaobject reference metafields. Decide the namespace, key and type before you create anything, because those are the parts Shopify treats as fixed. Keep data you’d need after an app is removed in definitions your store owns.

Then mark what’s left. Product reference lists, metaobject pages that need their own sections, variant-level imports, and anything a Function or checkout extension has to read are the items to scope as theme or app work. Everything else is configuration.

About the author

BLKDG Team

Not sure where the gap is? That's exactly what the Digital Marketing Growth Audit is for.

A free, no-obligation look at where your site can win more traffic and conversions, with a clear digital marketing roadmap to get there. Just a straight read on where your digital presence stands and where it's headed.