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:

Anchor to Structured metafieldsStructured metafields

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

• Data validation
• Permissions
• Optional features
• Conditional usage

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:

[product.metafields.app.care_guide]
type = "single_line_text_field"
name = "Care Guide"
description = "How to care for the product."
access.storefront = "public_read"

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 {
        name
      }
      access
    }
  }
}

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.

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:

[metaobjects.app.feature]
name = "Feature"
display_name_field = "title"
access.admin = "merchant_read_write"
access.storefront = "public_read"
capabilities.translatable = true

[metaobjects.app.feature.fields.title]
name = "Highlight Title"
type = "single_line_text_field"
required = true

[metaobjects.app.feature.fields.description]
name = "Description"
type = "multi_line_text_field"
required = true

[metaobjects.app.feature.fields.creative]
name = "Creative"
type = "file_reference"

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
      }
    }
  }
}

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:

[product.metafields.app.key_features]
name = "Key features"
description = "Key features of the product."
type = "list.metaobject_reference<$app:feature>"
access.storefront = "public_read"

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
    }
  }
}

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

• 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.