Metafields and Metaobjects

The MetafieldsSetInput documentation of 2026-10 states that a namespace is 3 to 255 characters and a key is 2 to 64 characters, both made of letters, digits, hyphens and underscores. If namespace is omitted in metafieldsSet, the app-reserved namespace is used. The Admin API and Liquid address a metafield as namespace.key; the search syntax adds a prefix, metafields.custom.roast_date.

Shopify publishes standard metafield definitions for common data (subtitle, ISBN, care instructions, ingredients) and standard metaobject definitions (currently product_review, available to approved partners only). A standard definition has a reserved namespace and key, a known type and preset access, does not count against the definition limits, and is interoperable across themes and apps. List the templates with standardMetafieldDefinitionTemplates, enable one with standardMetafieldDefinitionEnable (or standardMetaobjectDefinitionEnable with the type), or declare it in shopify.app.toml with standard_metafields = ["descriptors.subtitle", "facts.isbn"] under [product.metafields]. A standard metafield definition is also enabled automatically the first time a value is written to its namespace and key. Once enabled, Shopify owns the schema while the values stay merchant-owned.

Source: Manage metafield definitions, Standard definitions

metafieldDefinitionCreate takes a MetafieldDefinitionInput. The fields of the 2026-10 schema are these.

The MetafieldOwnerType enum of 2026-10 has 26 values: API_PERMISSION, ARTICLE, BLOG, CARTTRANSFORM, COLLECTION, COMPANY, COMPANY_LOCATION, CUSTOMER, DELIVERY_CUSTOMIZATION, DISCOUNT, DRAFTORDER, FULFILLMENT_CONSTRAINT_RULE, GIFT_CARD_TRANSACTION, LOCATION, MARKET, MEDIA_IMAGE, ORDER, ORDER_ROUTING_LOCATION_RULE, PAGE, PAYMENT_CUSTOMIZATION, PRODUCT, PRODUCTVARIANT, SELLING_PLAN, SHOP, TRANSFER (added for inventory transfers in 2026-07) and VALIDATION. There is no CART owner: cart metafields exist on the Storefront API and in checkout, and are copied to order metafields when the order is created. App-data metafields use the AppInstallation resource as owner and need no definition.

A definition in a namespace that is not reserved is merchant-owned. Pocket Coffee needs the roast date to be editable by staff, readable by the theme and by a headless storefront, and filterable in the admin. The mutation takes the input as a variable, which is how an app that lets merchants configure their own fields would call it.

Variables:

Source: Manage metafield definitions, GraphQL Admin API example

A merchant-owned definition cannot be declared in shopify.app.toml. The app needs the owner’s scope: write_products for product metafields, write_customers for customer metafields, write_orders for order metafields and so on. Metaobject-reference types need the metaobject scopes too.

The same mutation with a $app namespace creates an app-owned definition. This one declares a lot code that must match a pattern and be unique across products. Prefer shopify.app.toml for definitions that are the same in every shop (see Declarative definitions); use GraphQL when the structure depends on what the merchant configures in your app.

Source: Manage metafield definitions, GraphQL Admin API example

metafieldDefinitions lists the definitions of one owner type, optionally filtered by namespace, key or a search query. metafieldDefinitionTypes lists every type with the validations it supports and whether it supports definition migrations. The validationStatus of a definition is ALL_VALID, SOME_INVALID or IN_PROGRESS after a validation change, and metafieldsCount and metafields(validationStatus:) show how many values exist and how many break the rules.

Source: Manage metafield definitions, Reading definitions

Only some parts of a definition can change after it is created.

Update takes the owner type, namespace and key (there is no id argument in 2026-10), and delete takes the definition’s ID. deleteAllAssociatedMetafields: true deletes the values with the definition; false keeps them as untyped metafields.

Source: Manage metafield definitions, Updating definitions

A definition that is declared in shopify.app.toml is read-only through the API: the mutation returns an error with the code APP_CONFIG_MANAGED. Change it in the file and deploy.

When a merchant uninstalls the app, Shopify deletes its app-owned definitions, whether they came from TOML or from GraphQL, and keeps the values without a definition for an unspecified time while cleanup runs asynchronously. If the app is reinstalled before cleanup, the definitions are recreated and the values reattached. TOML definitions are deleted and recreated with new GIDs; GraphQL definitions can outlive the uninstall until cleanup removes them. Shopify does not guarantee the retention period, and a definition ID is not a stable identifier across an uninstall: look definitions up by owner type, namespace and key. The same applies to a definition you remove from the TOML file and deploy: the values are retained for a short period and are reattached, with a new GID, if you add the definition back before cleanup.

Most types are limited to 64 KB (65,536 bytes). The exceptions are id and url (2 KB each) and json (128 KB). Since API version 2026-04, writes of JSON values are limited to 128 KB; apps that already used JSON metafields before 2026-04-01 keep the previous 2 MB limit, and new apps that need more can ask for an exception. Large values already stored stay readable in every version. A list holds at most 128 items (1,024 for metaobject references), and each item obeys the size limit of its single type. Shopify Functions input queries do not return metafield values larger than 10,000 bytes: the value is stored and the Admin API returns it, but the Function receives null.

Validations constrain what a definition accepts. In GraphQL each is a {name, value} pair of strings; in TOML they are keys under validations.

Source: List of validation options

The access block of a definition says who may read and write the values.

Since 2026-06-16 a metafield on the app resource needs a definition with customer-account access to be returned by the Customer Account API; metafields owned by customers and orders were not affected. The documentation adds that, for merchant-owned metafields, the Customer Account API access can be changed only in the Shopify admin. The enum values PRIVATE, PUBLIC_READ and PUBLIC_READ_WRITE of the admin access still exist in the schema for reading old data but are never returned for metaobjects and cannot be set.

Source: About metafields, Permissions

Capabilities switch on optional behaviour for a definition.

The metafieldInteger collection condition is removed in API version 2027-01. The documentation table of TOML capabilities still marks analyticsQueryable as unsupported; the developer changelog of 2026-10-20 states that declarative definitions now accept capabilities.analytics_queryable, so this page follows the changelog.

Source: Use metafield capabilities

The documentation pages disagree on the app-level definition counts (the limits pages and a changelog give larger numbers than the TOML reference). Design for the smaller number when the definitions are declared in TOML and treat the larger one as an upper bound for definitions created by GraphQL. Standard definitions do not count.

metafieldsSet has a dynamic cost since 2026-09-15: 10 + sum(distinct owners of a type * weight of that type), with weights of 10 for orders, 4 for products, 2 for variants and 1 for collections, customers and the shop. Setting two metafields on one product, one on another product and one on a variant costs 10 + 2*4 + 1*2 = 20. Cost is charged per mutation invocation, so aliases do not share the base cost, and putting all metafields of a resource in one call is the cheapest way to write them.

Source: Metafield limits

metafieldsSet creates or updates up to 25 metafields in one atomic call: if one is invalid, none is saved. Each entry has an ownerId, a namespace (default: the app-reserved one), a key, a value string and a type. The type is optional when a definition exists and required otherwise. compareDigest turns the call into a compare-and-set: it is applied only if the stored value still matches the digest you read earlier, and null means "only if it does not exist yet".

Variables for a Pocket Coffee batch, including a reference to a metaobject entry, a list and an app-owned boolean:

Source: metafieldsSet

productCreate, productUpdate, productSet and the corresponding customer, order and collection mutations accept a metafields list of MetafieldInput (namespace, key, type, value, optionally id) next to the resource fields. In API version 2026-10 the product mutations take the resource as product: (a ProductUpdateInput), not the older input: that several guide pages still show.

Variables:

Source: Manage values, Creating metafields

The second operation reads a product by a custom ID: an id-typed or unique metafield that holds the ERP’s lot or product code. Lookup by custom ID works for products, variants, collections, customers, orders and locations, and create-or-update by custom ID for products (productSet, productUpdate) and customers (customerSet).

Source: Working with custom IDs

Read a metafield through its owner: metafield(namespace:, key:) for one, metafields(namespace:, first:) for a connection. value is always a string; jsonValue parses it for you, and reference and references resolve reference types in the same request. compareDigest is what you pass back to metafieldsSet. metafieldsDelete removes specific values and keeps the resource; deleting the resource deletes its metafields.

Source: Manage values, Reading metafields

Because everything is a string, the most common write errors are formatting errors.

Source: List of data types

An app-data metafield belongs to the app installation, needs no definition and is invisible in the admin. Only your app reads it through the Admin API, and Liquid reads it through the app object. It suits per-shop configuration: a feature tier, a sync cursor, or a boolean that decides whether an app block is shown (available_if).

Source: About metafields, App-data metafields

Source: Use metaobject capabilities

Each definition can hold 1,000,000 entries (the plan-based limits of 64,000 and 128,000 were removed in 2025-10). A list metafield can reference up to 1,024 entries. Liquid imposes its own, much lower, limits per page render, listed in Liquid limits.

The topics metaobjects/create, metaobjects/update and metaobjects/delete require a filter of the form type:<type> (several types are joined with OR, wildcards are not supported). For an app-owned definition the filter must use the stored form app--<app id>--<name>, not the $app: shorthand. Metafield definition changes have the topics metafield_definitions/create, metafield_definitions/update and metafield_definitions/delete. Since 2026-07-21 Events subscriptions can also trigger on changes to specific metafields of products, orders, customers, collections and locations, for both $app and merchant-owned metafields.

Source: Webhook filters, topics that require a filter

A metafield is declared as [<owner>.metafields.<namespace>.<key>] and a metaobject as [metaobjects.app.<name>] with [metaobjects.app.<name>.fields.<key>] tables for its fields. The owner is the snake-case form of the owner type: product, product_variant, customer and order in the guides; the other owner types follow the enum names in lower case. The namespace segment app means $app; any other segment creates a sub-namespace of the app, so [product.metafields.club.eligible] declares $app:club and eligible, which is stored as app--<app id>--club. Only app-owned definitions can be declared in TOML; the file cannot create custom or other merchant-owned ones.

This file declares the Coffee Club tier metaobject, the product, customer and order metafields that the Function, the theme app extension and checkout use, and the unique lot code. It also needs the scopes of the owner types it touches.

Source: Manage metafield definitions, TOML reference

Deploy with shopify app deploy. Remove a block and deploy again to delete the definition; the values are kept for a short period and reattached if the block comes back.

shopify app import custom-data-definitions (announced on 2026-01-22 as import-custom-data-definitions for CLI 3.89; CLI 5.0.0 lists it with a space) reads the app-owned definitions of a development store, such as $app metafields and $app: metaobject types, and prints the equivalent TOML without writing a file. Review it, copy it into shopify.app.toml, run shopify app dev to test and shopify app deploy to distribute, then delete the code that created the definitions at runtime. Values keep working unchanged. The command needs a development store and a login, so it was not run here; its --help was read.

shopify app build --no-input validates the app configuration, but it does not look inside the custom data tables: a misspelled access value, a reference to a metaobject that is not declared, a missing name, an unknown type and an unknown owner are all accepted, and Shopify rejects them only at deploy. A short script catches the common mistakes earlier. It parses the TOML (npm i smol-toml), resolves $app: references against the declared metaobjects, checks the access values, the owner of cart_to_order_copyable, the display field, the counts of the limits table, and prints the namespace that each declaration resolves to. It does not know the list of types or owner types, which Shopify validates on deploy.

Source: Manage metafield definitions, TOML limitations

Run on the file above it prints:

Run on files with one mistake each (a reference to $app:missing, access.admin = "public_read", a missing name, cart_to_order_copyable on a product, access.storefront = "everyone") it printed, one per file:

A resource’s metafields property takes a namespace and then a key: {{ product.metafields.custom.roast_date }}. The result is a metafield object with three properties, value, type and list?, and it is nil when no value is set, so test it with blank and not with the value. Always read .value explicitly so that the code states what it expects.

Source: Liquid objects: metafield

Three details cause most of the confusion.

metafield_tag generates an element for the metafield: a <time> for dates, a <span> for numbers and text, an <a> for URLs and references, a <div> for rich text, a <script type="application/json"> for JSON, an <img> or <video> for files, and so on, each with a class such as metafield-date. metafield_text returns plain text (the title of a referenced product, the URL of a file, the number). Neither supports every list type: both handle list.single_line_text_field and list.metaobject_reference only. Dates are localized to the visitor.

Source: metafield_tag

The global metaobjects object gives access to published entries by type and handle: {{ metaobjects.origin.yirgacheffe.name.value }} or, with brackets, {{ metaobjects['origin']['yirgacheffe'].name.value }}. An entry is reached through the field keys of its definition, and each field is a metafield object (so .value, .type). The system property groups the built-in properties so that they do not collide with field keys: system.handle, system.id, system.type, system.template_suffix and system.url (the relative URL, set only when the definition has the online store capability). metaobjects.origin.values loops over every entry of a definition, and values_count returns their number. shop.metaobjects was the older path; it still works and has been deprecated since 2025-01-28.

When the publishable capability is on, a DRAFT entry is invisible: a direct lookup returns nil and loops skip it. A metaobject definition whose entries are web pages (renderable and onlineStore) adds a template templates/metaobject/<type>.json or .liquid; inside it the metaobject object is the entry being rendered, and metaobject.system.template_suffix returns the alternate template assigned to an entry, or nil.

These limits apply to each page render. They are separate from the storage limits (a definition can hold a million entries, but one page can load only some of them). Exceeding a per-type limit renders a Liquid error instead of the entries.

The size of a reference list and of values reports the real total, except that values.size and values_count stop at 25,001 for definitions with more than 25,000 entries. The 20-handle limit and the impossibility of paginating a lookup by handle are the reasons to prefer values with paginate when you do not know the handles in advance.

Source: Metaobject limits, Liquid limits

The code that runs inside your own theme app extension can use the shorthand: $app:sub for a namespace or a metaobject type, resolved to your app’s reserved name. The merchant’s theme cannot; it addresses the same data with the stored name app--<app id>--sub. Which spelling to use depends on who owns the Liquid file.

Source: Configure theme app extensions, Reserved prefixes

An app block can hide itself until the app has finished a setup step: available_if in the block’s schema takes a reference to a boolean app-data metafield, and the block is rendered and offered in the theme editor only when the value is true. The Pocket Coffee block below uses {{ app.metafields.club.enabled }}, written by the SetAppDataMetafield mutation shown earlier.

A rule of thumb for safe data: store every value that your extension renders as markup, CSS or JavaScript in an app-owned or app-data metafield, with MERCHANT_READ access. A public namespace such as custom can be changed by other installed apps, by staff and collaborators who can edit the resource, and by translations (a translation of a translatable metafield replaces what Liquid renders for that locale). Output every value through escape unless it is already safe, and never put secrets in a metafield: Liquid reads them whatever the storefront access says. The app security checks of the App Store report shared-namespace metafield values that reach HTML, JavaScript or URL output.

Source: Store storefront settings where only your app can write them

A section or block setting of type metaobject opens a picker for entries of one definition (metaobject_type is required); the value is a metaobject object, or blank when nothing is chosen or the entry is gone. metaobject_list is the multiple version (limit defaults to and cannot exceed 50) and its value can be paginated. Custom definitions are not allowed in themes that are listed in the Theme Store, which must use standard definitions; apps can use the settings with their own app-owned definitions.

Dynamic sources let a merchant connect a section or block setting to a metafield in the theme editor, so the setting follows the product (or collection, or page) being rendered. They are available for section and block settings only, not for general theme settings. Theme blocks reach the nearest resource of a type through closest, for example closest.product. Metaobjects with storefront visibility are available as dynamic sources in any setting, and market- specific values (metafields and metaobjects that are localized per market) follow the market.

Source: Dynamic data sources

The following files were added to a copy of the Skeleton theme (shopify theme init default). The roast date badge reads the merchant-owned custom.roast_date and shows how fresh the beans are. date formats the stored ISO date, 'now' | date: '%s' gives the current Unix time, and the floor filter keeps the day count an integer whatever the Liquid engine. doc documents the snippet’s parameter so Theme Check validates calls to it.

Source: Liquid objects: metafield

The strings live in the locale file. Shopify’s translation filter picks the one or other form from count.

Source: Storefront locale files

The origin card is a theme block, so a merchant can add it to any section that accepts theme blocks. It reads the metaobject reference, its fields (a file_reference photo, a rich_text_field story) and the list of tasting notes.

Source: Theme blocks, dynamic sources and the closest resource

A section lists every origin with pagination and highlights one chosen in the editor through a metaobject setting.

Source: Input settings, metaobject

When the origin definition has the online store capability each entry is a page. The template and its section render the entry through the metaobject object.

Source: Liquid objects: metaobject

A section that accepts theme blocks puts the badge and the origin card on the product page.

Source: Theme blocks

shopify theme check knows every Shopify tag, filter, object, the section and block schema (including the metaobject_type of a setting) and the translation files. On the files above it printed:

To confirm that it checks what it should, a snippet with deliberate mistakes (a misspelled filter, a translation key that does not exist, a missing snippet, an img tag without dimensions, a deprecated filter, an unused variable) and a section whose metaobject setting lacked metaobject_type were added to a copy. Theme Check reported:

Source: Theme Check

shopify theme metafields pull writes the definitions of the store to a local file that the Liquid language server uses to complete product.metafields.custom. in the editor. It needs a store and a password, so it was not run.

A metafield or metaobject is returned only when its definition has access.storefront = PUBLIC_READ. The separate metafieldStorefrontVisibilityCreate mutation was removed in API version 2025-01; a metafield that was exposed with it must have its definition created or updated with the access setting. Reading metafields and metaobjects needs a Storefront access token: the tokenless access of 2026 covers products, collections, selling plans, search, pages, blogs, articles and the cart, but not metafields, metaobjects, product tags or menus. Use the public token from a browser or the private token from a server (with the buyer IP), as described on the Storefront API and Headless with Hydrogen page.

Resources that implement the HasMetafields interface have metafield(namespace:, key:) and metafields(identifiers: [{namespace:, key:}]). The list form returns one slot per identifier, null in the slot of an identifier that has no readable value, so the order of the response matches the order of the request. These types implement it in 2026-10: Article, Blog, Cart, Collection, Company, CompanyLocation, Customer, Location, Market, Order, Page, Product, ProductVariant, SellingPlan and Shop. A Metafield returns value, type, list, reference and references (for reference types) and parentResource. The reference union can be an Article, Collection, GenericFile, MediaImage, Metaobject, Model3d, Page, Product, ProductVariant or Video.

Metaobjects have two root fields: metaobject(handle: {type:, handle:}) or metaobject(id:), and metaobjects(type:, sortKey:, first:, after:, ...). The Storefront API has no field filter for metaobjects: filter in the Admin API or on the client. A Metaobject has handle, type, fields, field(key:), id, updatedAt, and, for definitions with the renderable and online store capabilities, seo and onlineStoreUrl. The seo title and description are fields themselves, so they need a selection of value. Only active entries are returned when the definition is publishable. The Storefront API accepts @inContext(country:, language:) to return the translation or the market-specific value of a field.

Source: Retrieve metafields with the Storefront API

The cart is the one place where the Storefront API writes metafields. cartCreate accepts metafields in its input and cartMetafieldsSet and cartMetafieldDelete change them, up to 25 per request. The key of these inputs is the namespace and the key together, custom.gift_message. If the shop has an order metafield definition with the same namespace and key and the cartToOrderCopyable capability, the value is copied to the order when it is created (since API 2026-04). Cart metafields set through the Storefront API do not trigger Shopify Functions: the Functions see them when the buyer goes to checkout or changes the cart. Checkout UI extensions read and write cart metafields too; checkout metafields were removed from checkout and customer account UI extensions in API 2026-04.

Source: cartMetafieldsSet

The Customer Account API reads and writes the metafields of the logged-in customer and their orders when the definition’s access.customerAccount allows it. App-owned metafields need a definition with that access to be returned (rule of 2026-06-16). == Using custom data in Functions and extensions

A Function’s input query can read the metafields of its function owner (a discount, a payment customization), of the cart, its lines' products and variants, the customer, the shop and the delivery options, and, since API 2026-04, app-owned metaobject entries by handle or ID through the shop field. The metaobject type must use the $app prefix; merchant-owned types are not available. The input query is limited to 3,000 bytes, to a calculated cost of 30 (a metafield costs 3, a metaobject root 1, a field(key:) 3, any other leaf 1) and to values of at most 10,000 bytes. Using a single json metafield for a complex configuration keeps both the query and the merchant interface simple, and changing the shape of a configuration is safest as an expand-and-contract migration: read the old and the new metafield, write both, migrate, then drop the old one.

The Coffee Club Discount Function reads a JSON configuration from the discount (created by the app with metafields on discountAutomaticAppCreate) and the $app:club.eligible flag of each product, and discounts only eligible lines.

Variables:

Source: Shopify Admin GraphQL: discountAutomaticAppCreate

The input query:

Source: Metafields for input queries

The Function (JavaScript, @shopify/shopify_function; the type RunInput is generated by shopify app function typegen from the query and the schema of the target):

The extension configuration:

Source: Metafields for input queries

shopify app build --no-input generated the types, bundled the JavaScript and compiled it to a 1,941-byte dist/function.wasm. shopify app function run executed the Wasm with this input (line 1 eligible, line 2 not):

and printed:

Source: shopify app function run

With "club": null (a discount that has no configuration) the output was {"operations": []}. The validation of the real input query against the complete schema of the target is done by the typegen step. The full Function story (targets, limits, deployment) is on the Shopify Functions page.

An extension declares the metafields it needs in shopify.extension.toml: for the whole extension or for one target, each with namespace, key and, since 2026-10, owner_type (CART, COMPANY, COMPANY_LOCATION, CUSTOMER, PRODUCT, PRODUCTVARIANT or SHOP). owner_type is optional in 2026-10 and required in 2027-01, when a deployment that omits it is blocked. An app-owned metafield is requested with namespace = "$app" or "$app:sub"; the fully qualified app--<app id> form is not supported there, and an extension can read only the app-owned metafields of its own app. The values arrive through shopify.appMetafields. Checkout and customer account extensions can use cart metafields (checkout) and order metafields (customer accounts) in place of the removed checkout metafields.

Source: Using metafields for custom data in checkout

This snippet is documented configuration and was not built: extension targets need a store and an account to preview. The Checkout Extensibility page covers the extension model.