Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 55 ยท Admin GraphQL API

Metafields and Metaobjects from the API

Store custom data on Shopify with metafields and metaobjects: definitions, namespaces, types, metafieldsSet, app-owned namespaces and a runnable type validator.

Shopify's built-in objects have a fixed set of fields. A product has a title and a vendor, but not "care instructions", "fabric weight" or "size chart". Merchants and apps need places to put their own data, and the platform offers two tools for it: metafields add extra named values to an existing object, and metaobjects are entirely new, structured objects that you can define yourself and reference from elsewhere.

This lesson explains both from an app developer's point of view: definitions, namespaces and keys, the value types, writing with metafieldsSet, reading, and the special app-owned namespace that keeps your data separate from other apps. Requests target Admin API version 2026-07 and are read-only here (they need a live shop). The runnable examples are stand-ins: a type validator that mimics how Shopify checks values, and a small in-memory store. Metafields also appear in the next chapters, for example as the configuration of a function in Building a Function from Scratch.

What a metafield is

A metafield is a piece of data attached to one owner: a product, a variant, a customer, an order, a collection or the shop itself, among others. It is identified by three things:

  • the namespace, a grouping name such as custom or my_app
  • the key, the name inside the namespace, such as fabric_weight
  • the owner, the object it belongs to

It also has a type and a value. The type controls how the value is validated and shown. Namespaces and keys use lowercase letters, digits, underscores and dashes, and they have length limits, so keep them short and descriptive. The pair namespace.key (for example custom.fabric_weight) is how you refer to a metafield in code, in Liquid and in search.

Definitions

A metafield can exist without any declaration, but the recommended way is to create a definition first. A definition says: for owner type PRODUCT, the metafield custom.fabric_weight has the type number_integer, a human name and optional validation rules. Definitions give you three benefits: values are validated, the Shopify admin shows a proper field for merchants to edit, and the data can be used in the theme editor and in filters.

GRAPHQL
mutation CreateDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
      key
      type { name }
    }
    userErrors {
      field
      message
    }
  }
}
JSON
{
  "definition": {
    "name": "Fabric weight (g/m2)",
    "namespace": "custom",
    "key": "fabric_weight",
    "type": "number_integer",
    "ownerType": "PRODUCT",
    "description": "Weight of the fabric in grams per square meter"
  }
}

As always, check userErrors (see Mutations and userErrors). A definition for a namespace and key that already exists is rejected.

Types and values

Every value is sent as a string, even for numbers and booleans, and the type tells Shopify how to parse it. Some commonly used types are:

Type Example value (as a string)
single_line_text_field Hand wash cold
multi_line_text_field text with line breaks
number_integer 180
number_decimal 4.75
boolean true or false
date 2026-09-01
date_time 2026-09-01T10:30:00Z
url https://example.com/care
color #1F6FEB
json {"sizes":["S","M"]}
money {"amount":"19.99","currency_code":"USD"}
rating {"scale_min":"1.0","scale_max":"5.0","value":"4.5"}
list.single_line_text_field ["cotton","linen"]
product_reference gid://shopify/Product/101

The list is long (dimensions, weights, volumes, file and metaobject references, and more), and it grows. Treat the table as a sample; the schema and the documentation for your API version are the authority. The key idea is that structured values (money, rating, lists, JSON) are JSON encoded inside the string, and references are global IDs.

Writing: metafieldsSet

metafieldsSet is the workhorse mutation. It creates or updates up to 25 metafields in one call (check the current limit), and because it sets a value, repeating it with the same input leaves the same result, which makes retries safe.

GRAPHQL
mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      namespace
      key
      value
      type
    }
    userErrors {
      field
      message
      code
    }
  }
}
JSON
{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/101",
      "namespace": "custom",
      "key": "fabric_weight",
      "type": "number_integer",
      "value": "180"
    },
    {
      "ownerId": "gid://shopify/Product/101",
      "namespace": "custom",
      "key": "materials",
      "type": "list.single_line_text_field",
      "value": "[\"linen\",\"cotton\"]"
    }
  ]
}

If any entry in the batch is invalid, the whole call is typically rejected with userErrors and nothing is saved, but confirm this behavior in the documentation for the version you use, and never assume. Needing the write_products scope (or the scope of whichever owner type you write to), an app can only write metafields for owner types it has been granted.

Reading

You read metafields as part of an object query, either one by namespace and key, or a list:

GRAPHQL
query ProductMetafields($id: ID!) {
  product(id: $id) {
    title
    weight: metafield(namespace: "custom", key: "fabric_weight") {
      value
      type
    }
    all: metafields(first: 20, namespace: "custom") {
      nodes {
        key
        value
        type
      }
    }
  }
}

The value always comes back as a string. Your code must parse it according to type: Number(value) for integers, JSON.parse(value) for lists and money.

App-owned namespaces

Namespaces are shared across the whole shop: another app, a theme developer or the merchant can also use custom. If two apps use the same namespace and key, they overwrite each other. To avoid that, apps get a reserved, app-owned namespace. You write $app in place of the namespace (and $app:name for a sub-namespace), and Shopify expands it to a unique, app-specific string (it looks like app--1234567--name). Only your app can write to it by default, and merchants can still see the data in the admin if you declare it that way.

JSON
{
  "ownerId": "gid://shopify/Product/101",
  "namespace": "$app",
  "key": "low_stock_threshold",
  "type": "number_integer",
  "value": "5"
}

Use the app-owned namespace for data that is part of your app's internal configuration (a threshold, a feature flag, an ID in your own system). Use a shared namespace such as custom when the data is meant for the merchant and the theme to share. App-owned definitions can also be declared in your app configuration file, which App Configuration with shopify.app.toml introduces.

Metaobjects

When a value has several fields of its own, a metafield becomes awkward. A metaobject is a custom object type that you define: for example a designer with a name, a photo and a biography, or a size_chart with rows of measurements. Each instance is a metaobject entry. Entries can be referenced from products through a reference-type metafield, shown in the theme, and edited by merchants in the admin.

A metaobject definition lists the fields (key, type, validation) and a type string that names it. An entry carries a handle and the field values:

GRAPHQL
mutation UpsertDesigner($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
  metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
    metaobject {
      id
      handle
      fields { key value }
    }
    userErrors { field message code }
  }
}
JSON
{
  "handle": { "type": "designer", "handle": "ada-lindqvist" },
  "metaobject": {
    "fields": [
      { "key": "name", "value": "Ada Lindqvist" },
      { "key": "bio", "value": "Designs linen basics in Gothenburg." }
    ]
  }
}

An upsert by handle creates the entry if it does not exist and updates it otherwise, which again makes the call safe to repeat. As with metafields, an app can own a metaobject type by prefixing it with $app:, for example $app:size_chart. The merchant's storefront reads entries through Liquid or the Storefront API, subject to the definition's access settings, so check that a definition is visible to the storefront if a theme or headless site needs it.

Choosing between the two:

Need Use
One extra value on a product, order or customer a metafield
A repeatable group of fields reused in many places a metaobject
Config for your own app on one shop a metafield in $app
Content that merchants edit as pages of structured data a metaobject

Try it: a type validator

Shopify validates values against types on its servers. The validator below is a stand-in that checks the string forms of a handful of types, so you can see exactly what "everything is a string" implies. It is deliberately simple; the real rules (limits, units, more types) are broader.

Node.js Validate metafield values by type

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that 2026-02-30 fails: the date check converts the text to a date and back, so a day that does not exist is caught instead of silently rolling over into March. Real validation is broader than this toy, so always treat the userErrors from Shopify as the final word.

A metafield store in miniature

The second stand-in models the identity rule: one value per owner, namespace and key. It also shows why $app matters, since two apps writing custom.threshold collide while their own namespaces do not.

Node.js Owner, namespace and key identify a value

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first pair overwrites; the second pair coexists. The real expansion of $app is different from this toy string, but the effect is the same: your namespace is yours alone.

Common mistakes

  • Sending numbers or booleans as JSON types. Values are strings: "180", not 180.
  • Skipping definitions. Without them, merchants get no editor, and typos create stray metafields.
  • Using a shared namespace for private app config. Another app can overwrite it. Use $app.
  • Storing huge or fast-changing data. Metafields are for small, mostly stable values. Put logs and large datasets in your own database.
  • Forgetting access. Metafields are not public by default for the storefront; storefront access is an explicit setting on the definition.
  • Not parsing by type. "true" is a truthy string in JavaScript; convert it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What three things identify a metafield?

    A metafield belongs to one owner and is addressed by namespace and key. Type and value describe its content.
  2. 2. How do you send the integer 180 in a metafieldsSet call?

    Every metafield value is a string. The type tells Shopify to parse and validate it as a whole number.
  3. 3. Why use the $app namespace for your app's internal settings?

    Shopify expands $app to an app-specific namespace, so keys cannot collide with those of other apps.
  4. 4. When is a metaobject a better fit than a metafield?

    Metaobjects model structured content with several fields that other objects can reference. A single value is simpler as a metafield.

Summary

  • Metafields add named values to existing objects; they are identified by owner, namespace and key and carry a type and a string value.
  • Create definitions first for validation, merchant-friendly editing and filtering.
  • metafieldsSet writes in batches and is safe to repeat; always read userErrors.
  • Structured values are JSON inside the string, and references are global IDs; parse by type when reading.
  • Use $app for your app's private data to avoid collisions.
  • Metaobjects are custom structured object types with entries, upserted by handle, for content and reusable data groups.

Next: Orders, Customers and Protected Data.