Skip to main content

About metafields and metaobjects

Shopify comes with many built-in data models like products, customers, and orders. Yet often while building for the varied and diverse needs of merchants you'll need a way to customize the data in Shopify:

  • Metafields to extend Shopify's resources with custom fields.
  • Metaobjects to create entirely new resources by making new custom objects.

Anchor to What are metafields?What are metafields?

Metafields are a flexible way to store additional details about existing Shopify resources, like products, orders, and many more. These custom fields can be almost anything, such as related products, release dates, internal approval status, or part numbers.

Metafields power experiences across Shopify. In the Shopify admin, they enable features like customer segmentation, smart collections, and product taxonomy. For customers, they enhance the shopping experience through product recommendations, product swatches, and customized checkouts using Shopify Functions.

Anchor to Unstructured metafieldsUnstructured metafields

Metafields serve as the foundation for extending Shopify's data model. At their core, metafields are key-value pairs that can be added to specific resources in Shopify:

  • Identifier: Composed of both namespace (drives ownership) and key.
  • Value: The raw value stored.
  • Type: How value is interpreted.

The type on an unstructured metafield can vary on an instance-by-instance basis. To ensure consistency, you need a metafield definition.

Example:

You work with a snowboard merchant who needs to store care instructions for each product. Starting simple, you add a custom.care_guide metafield to a product by using the productUpdate mutation:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
productUpdate(input: {
id: "gid://shopify/Product/1",
metafields: [
{
namespace: "custom",
key: "care_guide",
value: "Wax once a season",
type: "single_line_text_field",
}
]
}) {
product {
metafield(namespace: "custom", key: "care_guide") {
value
type
}
}
}
}

JSON response

{
"data": {
"productUpdate": {
"product": {
"metafield": {
"value": "Wax once a season",
"type": "single_line_text_field"
}
}
}
}
}

Anchor to Structured metafieldsStructured metafields

Metafields covered by a metafield definition, or structured metafields, have consistent types amongst other optional configurations:

Example:

In this example, you'll add a definition to your snowboard merchant to ensure all products have a custom.care_guide metafield with a type of single_line_text_field that is also accessible to storefronts:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metafieldDefinitionCreate(definition: {
name: "Care Guide",
namespace: "custom",
key: "care_guide",
description: "How to care for the product.",
type: "single_line_text_field",
ownerType: PRODUCT,
access: {
storefront: PUBLIC_READ,
},
}) {
createdDefinition {
name
namespace
key
type
access
}
}
}

JSON response

{
"metafieldDefinitionCreate": {
"createdDefinition": {
"name": "Care Guide",
"namespace": "custom",
"key": "care_guide",
"type": "single_line_text_field",
"access": {
"storefront": "PUBLIC_READ"
}
}
}
}

Anchor to What are metaobjects?What are metaobjects?

Metaobjects are a powerful way to create and reuse custom data structures beyond Shopify's standard resources. They exist independently and can be referenced by metafields to connect with standard resources like products, orders, and customers.

Key terms related to metaobjects:

  • Definition: The structure outlining the fields and properties for your metaobjects.
  • Entry: An instance of the associated definition.
Note

MetaobjectFields use the same types as metafields.

Metaobject definitions, beyond defining the fields, also offer control over:

Example:

Suppose a merchant wants a Feature resource in Shopify. You can represent that with a new metaobject definition:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metaobjectDefinitionCreate(definition: {
type: "$app:feature",
access: {
admin: MERCHANT_READ_WRITE,
storefront: PUBLIC_READ,
},
capabilities: {
translatable: { enabled: true },
},
displayNameKey: "title",
fieldDefinitions: [
{ key: "title", name: "Highlight Title", type: "single_line_text_field", required: true },
{ key: "description", name: "Description", type: "multi_line_text_field", required: true },
{ key: "creative", name: "Creative", type: "file_reference" },
]
}) {
metaobjectDefinition {
id
type
fieldDefinitions {
key
name
type
}
}
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/1",
"type": "app--123456--feature",
"fieldDefinitions": [
{
"key": "title",
"name": "Highlight Title",
"type": "single_line_text_field"
},
{
"key": "description",
"name": "Description",
"type": "multi_line_text_field"
},
{
"key": "creative",
"name": "Creative",
"type": "file_reference"
}
]
}
}
}
}

The merchant's products have a set of key features, so you'll also need to create a product metafield definition that references the Feature metaobject definition you just created:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metafieldDefinitionCreate(definition: {
name: "Key features",
key: "key_features",
description: "Key features of the product.",
type: "list.metaobject_reference",
ownerType: PRODUCT,
access: {
storefront: PUBLIC_READ,
},
validation: {
metaobjectDefinitionId: "gid://shopify/MetaobjectDefinition/1",
},
}) {
createdDefinition {
namespace
key
type
}
}
}

JSON response

{
"metafieldDefinitionCreate": {
"createdDefinition": {
"namespace": "app--123456--key_features",
"key": "key_features",
"type": "metaobject_reference"
}
}
}

With those in place, you can create Feature entries and reference as many as you want in a product's key_features metafield. These entries can be reused across products, making it easy to manage and update.

Anchor to Developer tools and resourcesDeveloper tools and resources

Explore the following tools and resources to work with metafields and metaobjects:

Anchor to MetafieldsMetafields

GraphQL Admin API

Manage metafields, metafield definitions, and app-data metafields using the GraphQL Admin API.

Storefront API

Retrieve metafields using the Storefront API.

Liquid

Access and display metafield data in themes using Liquid.

Anchor to MetaobjectsMetaobjects

GraphQL Admin API

Manage metaobjects and their definitions using the GraphQL Admin API.

Storefront API

Retrieve metaobjects using the Storefront API.

Liquid

Access and display metaobjects in themes using Liquid.

Anchor to Next stepsNext steps

Was this page helpful?