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 Standard metafield definitionsStandard metafield definitions

Shopify provides standard metafield definitions that you can use in your apps. These are predefined metafield definitions that Shopify maintains for common use cases like product facts, descriptors, and more.

Anchor to ExampleExample

You're building an app for a bookstore that needs to display book subtitles and ISBN numbers. Instead of creating custom metafield definitions, you can use Shopify's standard descriptors.subtitle and facts.isbn metafield definitions across different resource types in your shopify.app.toml file:

[product.metafields]
standard_metafields = ["descriptors.subtitle", "facts.isbn"]

[product_variant.metafields]
standard_metafields = ["descriptors.subtitle"]

# Enable subtitle standard metafield on product
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/1",
    ownerType: PRODUCT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

# Enable ISBN standard metafield on product
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/3",
    ownerType: PRODUCT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

# Enable subtitle standard metafield on product variant
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/1",
    ownerType: PRODUCTVARIANT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

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 Connecting metaobjects to other entitiesConnecting metaobjects to other entities

Use metafields with reference types to connect Shopify resources (like products and orders) to metaobject entries:

• Single reference: Use metaobject_reference to link to one metaobject entry.
• Multiple references: Use list.metaobject_reference to link to multiple entries of the same metaobject type.
• Mixed references: Use mixed_reference or list.mixed_reference to link to entries from different metaobject types.

In your app configuration, use the $app: prefix to connect a metafield to a custom metaobject type:

For standard metaobjects, use the bare metaobject type name without the $app: prefix:

Anchor to Standard metaobject definitionsStandard metaobject definitions

Shopify provides standard metaobject definitions that you can use in your apps. These are predefined metaobject definitions that Shopify maintains for common use cases such as product_review and shopify--qa-pair.

Anchor to ExampleExample

You're building an app to add customer feedback features to products, including both reviews and Q&A. Instead of creating custom metaobject definitions from scratch, you can use Shopify's standard product_review and shopify--qa-pair metaobject definitions in your shopify.app.toml file:

[metaobjects]
standard_metaobjects = ["product_review", "shopify--qa-pair"]

# Enable product review standard metaobject
mutation {
  standardMetaobjectDefinitionEnable(type: "product_review") {
    metaobjectDefinition {
      type
      name
      fieldDefinitions {
        key
        name
      }
    }
  }
}

# Enable Q&A pair standard metaobject
mutation {
  standardMetaobjectDefinitionEnable(type: "shopify--qa-pair") {
    metaobjectDefinition {
      type
      name
      fieldDefinitions {
        key
        name
      }
    }
  }
}

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.