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. Shopify’s custom data overview (opens in new tab) says “Metafields allow you to extend an existing platform data model, such as products, customers, and orders with your own custom data.” The same page says “Metaobjects allow you to create an object with multiple fields when your data is best represented by multiple fields.”

Because the data sits outside the theme, it survives a theme change. Shopify’s page on displaying metaobjects (opens in new tab) uses a profile example and says you can add the entries to multiple areas of your theme, “as well as add them to a new theme without recreating the data.” 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 is a metafield in Shopify? It’s an extra field on a resource Shopify already has. Shopify’s developer docs on metafields (opens in new tab) describe them as key-value pairs 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. Shopify’s data modeling guide (opens in new tab) maps the two onto database terms: 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. The Help Center’s own examples of metaobjects are a product highlight, an influencer profile, an FAQ and an event appearance.

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

Shopify’s developer overview of custom data (opens in new tab) gives the rule in a table: use a metafield when the data describes something Shopify already has, such as a product, order or customer, and a metaobject when the data doesn’t belong to an existing object. The same page says “Most apps use both: a metaobject defines the record, and a metafield attaches 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.

Shopify’s data modeling guide adds one instruction for relationships: “Don’t store handles or IDs in plain text fields (single_line_text_field) to create relationships.” A reference type keeps the link intact, and Shopify’s data type list (opens in new tab) says a deleted product or variant is automatically removed from every list metafield that references it. A handle typed into a text field gets no such cleanup.

A definition is the schema for a metafield. Shopify’s Help Center page on the parts of a definition (opens in new tab) lists a name, a namespace and key, 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, and the page’s example identifier is custom.color.

The namespace groups related fields. Shopify’s custom data terminology page (opens in new tab) says “Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name.” The namespace also signals ownership: Shopify’s developer docs on metafields (opens in new tab) say app-owned metafields use a reserved app namespace and merchant-owned ones can use any namespace that isn’t reserved, with custom as the example.

The type decides what the value can hold and where it can be used. The Help Center’s content types page (opens in new tab) groups types into seven categories: date and time, measurement, number, text, reference, other and advanced. That page’s seven tables list 57 content types, and the developer type list (opens in new tab) counts 113 type identifiers because it lists every list form separately. The developer page also says “Metaobjects use the same data types.”

A metafield can exist without a definition, and Shopify calls that an unstructured metafield. Shopify’s definitions reference (opens in new tab) says “Without definitions, metafields are untyped strings that can’t be edited in the Shopify admin or validated.” Shopify’s terminology page says these are typically made by an app.

Shopify also ships standard definitions with reserved namespaces and keys, such as descriptors.care_guide and reviews.rating. The standard definitions list (opens in new tab) lists 16 of them, including product subtitle, care guide, ISBN, related products and complementary products. Shopify’s page on adding definitions (opens in new tab) says “Whenever possible, use a standard definition for your metafields.”

Per Shopify’s definitions reference (opens in new tab), the name, description, validations and access permissions of a definition can be updated. The same table marks the namespace and key as immutable, the type as something that can’t be changed, and the owner type as something that can’t be migrated. Shopify’s data type page describes changing a type as possible only with caveats, including values that become invalid, so plan as if the type is fixed.

Validations can be tightened later, with a catch the same page states: “Tightening validations may fail if existing metafields violate the new constraint.” Shopify’s page on validation errors (opens in new tab) says that if some values are invalid, you can’t use the metafield until every error is fixed. For metaobjects, Shopify’s metaobject definitions reference (opens in new tab) says “Plan your type identifiers carefully: Type identifiers can’t be changed after creation.”

Deletion is permanent. Shopify’s page on deleting metafields (opens in new tab) says “Deleting metafields that are connected to your theme can cause display errors for customers visiting your online store.” Deleting a metaobject definition deletes all of its entries, according to Shopify’s page on building a metaobject (opens in new tab).

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

On October 24, 2025, Shopify’s developer changelog (opens in new tab) announced higher limits for both structures. For metaobject entries it says “The 1,000,000 entry limit per definition removes 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. Shopify’s metaobject limits page (opens in new tab) gives merchants 128 metaobject definitions on the Basic, Shopify and Advanced plans 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, the metafield limits page (opens in new tab) says “Merchants can create up to 256 metafield definitions per resource type.” Products, variants, customers and orders each get their own 256. The same page gives each installed app its own 256 metafield definitions per resource type, and the changelog says apps aren’t competing with each other for definition space. The Help Center’s page on adding definitions (opens in new tab) says “You can have up to 250 metafield definitions.”

Value size is capped per metafield. The limits page puts most types 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.

Pinning controls which fields show on a record in the admin. Shopify’s pinning page (opens in new tab) says only pinned metafields display automatically and that you can pin up to 50 definitions 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. The metafield limits page allows 128 definitions to power smart collections, 50 to 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 in Shopify come from three places: standard definitions, custom definitions you create, and category metafields. Shopify’s category metafields page (opens in new tab) says “Category metafields map to specific product categories in Shopify’s Standard Product Taxonomy.” Shopify’s custom data terminology page (opens in new tab) describes the taxonomy as a predefined, standardized list of categories, attributes and attribute values for products.

Assigning a category is what makes the attributes available. Shopify’s metafields page (opens in new tab) uses the Shirts category as its example, which makes available category metafields for size, neckline, sleeve length type, top length type, age group, fabric, target gender, clothing features and color. The same page says “Category metafields use metaobjects and metaobject entries for the values,” and the category metafields page says some are added by default based on Shopify Magic predictions.

Custom product metafields can join that card. Shopify’s page on adding category metafields (opens in new tab) says “You can assign one or more categories to your custom product metafields,” 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 same page’s list of Standard Product Taxonomy limitations includes “Custom attributes are currently not supported,” and Shopify’s Search & Discovery filters page (opens in new tab) says the standard metaobject definitions behind those attributes can’t be modified. Entries are editable, and edits to an existing entry update everywhere that entry is connected.

Category metafields can also drive variants. Shopify’s page on adding variants with metafields (opens in new tab) says you can connect a variant option to a category or product metafield of the metaobject reference list type. Shopify’s category metafields page says color entries used as variant options can display as swatches on storefront product pages.

A field in the admin does nothing for a shopper until a template renders it. Shopify documents 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.

Shopify’s page on displaying metafields (opens in new tab) says “You can connect metafields to your theme by adding sections or blocks that support dynamic sources.” The theme has to cooperate. Shopify’s sections and blocks page (opens in new tab) says “Not all sections or blocks support dynamic sources.”

The connection is made once per template, not once per product. Shopify’s care instructions walkthrough (opens in new tab) says the section isn’t filled in for products without a value for that metafield, “That means you can set up a single product template that’ll work 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. Per Shopify’s dynamic sources reference (opens in new tab), a text setting 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.

The same reference caps how many connections a theme can hold. Its limits table allows 100 dynamic sources in a JSON template and 50 in a single setting.

Metaobjects connect at the block level. Shopify’s page on connecting metaobjects (opens in new tab) says “Connecting a metaobject to a block automatically maps compatible fields to the block’s settings,” and that a list field adds each entry in the list to the block setting. The same page says “You need to ensure the metaobject has Storefronts access to display it on your online store.”

Metaobject entries can render as web pages. Shopify’s page on building web pages with metaobjects (opens in new tab) says “You can use metaobjects to build repeatable landing pages for your online store,” in three steps: create a definition with storefront access, create entries, and create a metaobject template. Shopify’s options page (opens in new tab) says the option to publish entries as web pages needs Storefront access selected.

One template serves every entry. Shopify’s metaobject template reference (opens in new tab) says the first template created for a metaobject 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. Shopify’s metaobject capabilities page (opens in new tab) says “The renderable capability exposes metaobject SEO fields to Liquid and the Storefront API,” and that metaobjects with it are included in the store’s sitemap. Entries in draft status aren’t served: Shopify’s Liquid reference for the metaobject object (opens in new tab) says a draft entry under a publishable definition returns nil.

Shopify metafields are read by more than the theme. Shopify’s developer overview (opens in new tab) lists themes, Shopify Functions, checkout and admin extensions, Shopify Analytics and the admin as places the same values are available.

In Liquid, the syntax in Shopify’s metafield object reference (opens in new tab) is {{ resource.metafields.namespace.key }}, and that reference says “You can’t create metafields in Liquid.” Metaobjects are read as {{ metaobjects.type.handle }}, per the Liquid metaobject reference (opens in new tab).

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

The Storefront API can’t write. Shopify’s Storefront API guide to metafields (opens in new tab) says “You can’t create, update, or delete metafields with the Storefront API.” Writes go through the GraphQL Admin API, where the limits page caps one metafieldsSet call at 25 metafields and a 10MB payload.

Filtering through the Admin API needs a capability enabled on the definition. A July 24, 2026 developer changelog entry (opens in new tab) says “Starting in API version 2026-10, the GraphQL Admin API returns an error when a query filters by a metafield that isn’t set up for filtering, instead of silently returning incorrect results.” Any integration that filters by metafield should be checked against that version.

Shopify’s page on metafields in Flow (opens in new tab) lists actions that update metafields on collections, companies, company locations, customers, orders, products, product variants and the shop. The same page says “You can create metafield definitions in workflows by using the Create metafield definition action.” For metaobjects, Shopify’s 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. Shopify’s input query docs (opens in new tab) say “You can query metafields from products, customers, carts, and more in your input queries,” and also “Metaobjects must be app-owned metaobjects.” Shopify’s metaobjects reference (opens in new tab) puts it the other way: “Merchant-owned types don’t work in function input queries.”

Size matters inside a function. The metafield limits page says “Shopify Functions input queries don’t return metafield values larger than 10,000 bytes,” and that 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, Shopify’s Metafields API for checkout UI extensions (opens in new tab) says it “provides 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. An April 27, 2026 changelog entry (opens in new tab) says checkout metafields were removed from checkout and customer account UI extensions as of API version 2026-04, and our post on checkout extensibility and Shopify Functions covers the extension model.

Storefront filters can run on custom data. Shopify’s Search & Discovery filters page (opens in new tab) says “Custom filters are based on the product options, metafields, or metaobjects used in your store,” and lists seven value types a metafield filter can use, among them single line text, decimal, integer, true or false and metaobject reference. The same page caps a store at 25 filters, shows at most 100 values per filter, and says collections with more than 5,000 products don’t display filters.

Automated collections accept metafield conditions on a short list of types. Shopify’s page on collections with metafields (opens in new tab) lists true or false, integer, decimal, rating and single line text, and caps a single collection 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. Shopify’s bulk editing page (opens in new tab) says “You can edit metafields in bulk for products, variants, collections, and customers.” Shopify’s product CSV page (opens in new tab) says a defined product metafield is included in product CSV exports, under a column header in the format (product.metafields..). The CSV page also says “Variant metafields aren’t supported for product CSV import/export.”

On February 12, 2026, Shopify’s changelog (opens in new tab) announced that “You can now group and filter by metafields 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. Shopify’s page on filtering and editing reports (opens in new tab) says a custom metafield only becomes available as a report dimension or filter once its Filter or group data in Analytics option is turned on. Shopify’s metafields page gives a customer loyalty tier as an 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. One changelog entry (opens in new tab) says “If you attach a metaobject to a product, variant, customer, or order through a metafield, those fields can now be used in Analytics,” and that app-created metaobjects are excluded until Analytics is turned on for the definition, by you or by the app. The other (opens in new tab) says category metafields 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. Shopify’s page on referencing metaobjects (opens in new tab) says that with a mixed reference, the metaobject’s fields can’t be used as dimensions or filters in reports. Shopify’s reports page adds that not every metaobject field type can be used.

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. Shopify’s page on displaying metafields (opens in new tab) says “Product reference lists require a custom section or a third-party theme that uses product list settings.”

Metaobject page templates. Shopify’s metaobject template reference (opens in new tab) says “The template is empty when it’s initially created in the Online Store editor. Merchants must add sections to their metaobject template 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. Shopify’s metafields page (opens in new tab) sends vintage themes, and metafield types a theme doesn’t support, to theme code edits. The content types page (opens in new tab) says a mixed reference needs developer support to be used on the storefront, describes JSON as a type for advanced use cases, and says rich text connects only to theme settings built for rich text.

The home page and other non-product templates. Shopify’s page on connecting metaobjects says that 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. Shopify’s CSV page says “To edit your 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. Shopify’s definitions reference (opens in new tab) says “When a user uninstalls your app, Shopify deletes its app-owned metafield definitions and temporarily retains the metafields and their values without a definition.” It also says “Shopify doesn’t guarantee how long metafields and their values are retained after an uninstall.” Data that has to outlive an app belongs in a merchant-owned definition.

The JSON size cap. The limits page holds JSON values 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.

Start with the fields that pass three checks: the value belongs to a product or variant, its type appears in Shopify’s dynamic sources table, 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 its metafield limits page says 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’s docs treat 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.