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) andkey
. - 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
JSON response
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
JSON response
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.
MetaobjectFields use the same types as metafields.
Metaobject definitions, beyond defining the fields, also offer control over:
- Permissions, such as storefront visibility.
- Optional features, such as translatable fields.
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
JSON response
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
JSON response
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
Manage metafields, metafield definitions, and app-data metafields using the GraphQL Admin API.
Retrieve metafields using the Storefront API.
Access and display metafield data in themes using Liquid.
Anchor to MetaobjectsMetaobjects
Manage metaobjects and their definitions using the GraphQL Admin API.
Retrieve metaobjects using the Storefront API.
Access and display metaobjects in themes using Liquid.
Anchor to Next stepsNext steps
- Learn how to own the custom objects and fields that your app defines in Shopify.
- Learn about all of the different types supported by metafields.
- Learn how to manage metafields using the GraphQL Admin API.
- Use metafields to link product options to the Shopify taxonomy.
- Learn how to work with metaobjects using the GraphQL Admin API.