Skip to main content

Manage metafield definitions

Metafield definitions enable you to include data validation for metafields, and enable users to add metafield values for resources in the Shopify admin. This guide shows you how to manage metafield definitions using the GraphQL Admin API.

Anchor to RequirementsRequirements

  • Your app can make authenticated requests to the GraphQL Admin API.
  • You're using the GraphQL Admin API version 2021-10 or higher.
  • Your app has access to the owner type that you want to associate with the metafield definition. You can only create metafield definitions for owner types that you have access to.

Anchor to Step 1: Create a metafield definitionStep 1: Create a metafield definition

You can create a metafield definition using the metafieldDefinitionCreate mutation. You can create only one metafield definition at a time.

The following example creates a metafield definition called Ingredients for the PRODUCT owner type, which stores multi-line text, such as a list of ingredients used to make the product.

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

GraphQL mutation

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
metafieldDefinitionCreate(definition: $definition) {
createdDefinition {
id
name
namespace
key
# add other return fields
}
userErrors {
field
message
code
}
}
}

Variables

{
"definition": {
"name": "Ingredients",
"namespace": "bakery",
"key": "ingredients",
"description": "A list of ingredients used to make the product.",
"type": "multi_line_text_field",
"ownerType": "PRODUCT"
}
}

JSON response

{
"metafieldDefinitionCreate": {
"createdDefinition": {
"id": "gid://shopify/MetafieldDefinition/1071456108",
"name": "Ingredients",
"namespace": "bakery",
"key": "ingredients"
},
"userErrors": []
}
}

Anchor to Step 2: Retrieve a metafield definitionStep 2: Retrieve a metafield definition

You can use the metafieldDefinition query to retrieve a metafield definition.

The following example retrieves a metafield definition by using its ID:

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

GraphQL query

{
metafieldDefinition(id: $id) {
name
namespace
key
description
ownerType
type {
name
}
}
}

Variables

{
"id": "gid://shopify/MetafieldDefinition/18776120"
}

JSON response

{
"data": {
"metafieldDefinition": {
"name": "Expiry Date",
"namespace": "food",
"key": "expiry_date",
"description": "The expiry date.",
"ownerType": "PRODUCT",
"type": {
"name": "date"
}
}
}
}

Anchor to Step 3: Update a metafield definitionStep 3: Update a metafield definition

You can use the metafieldDefinitionUpdate mutation to update a metafield definition. You can update only the name and description of a metafield definition.

The following example changes a metafield definition's name from Pizza size to Pizza size (inches):

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

GraphQL mutation

mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
metafieldDefinitionUpdate(definition: $definition) {
updatedDefinition {
id
name
namespace
key
# add other return fields
}
userErrors {
field
message
code
}
}
}

Variables

{
"definition": {
"name": "Pizza size (inches)",
"namespace": "bakery",
"key": "pizzasize",
"ownerType": "PRODUCT"
}
}

JSON response

{
"metafieldDefinitionUpdate": {
"updatedDefinition": {
"id": "gid://shopify/MetafieldDefinition/1071456109",
"name": "Pizza size (inches)",
"namespace": "bakery",
"key": "pizza_size"
},
"userErrors": []
}
}

Anchor to Step 4 (Optional): Delete a metafield definitionStep 4 (Optional): Delete a metafield definition

To delete a metafield definition, use the metafieldDefinitionDelete mutation. You can also set an option that, when selected, deletes all metafields that use that definition.

The following example deletes the metafield definition for bakery.ingredients, and also deletes all metafields that use the definition.

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

GraphQL mutation

mutation DeleteMetafieldDefinition {
metafieldDefinitionDelete(id: $id, deleteAllAssociatedMetafields: $deleteAllAssociatedMetafields) {
deletedDefinitionId
userErrors {
field
message
code
}
}
}

Variables

{
"id": "gid://shopify/MetafieldDefinition/18710584",
"deleteAllAssociatedMetafields": true
}

JSON response

{
"metafieldDefinitionDelete": {
"deletedDefinitionId": "gid://shopify/MetafieldDefinition/18710584",
"userErrors": []
}
}

Anchor to Next stepsNext steps

Was this page helpful?