Choose a version:

metafieldDefinitionCreate

mutation

Requires API client to have access to the namespace and the resource type associated with the metafield definition.

Creates a metafield definition. Any metafields existing under the same owner type, namespace, and key will be checked against this definition and will have their type updated accordingly. For metafields that are not valid, they will remain unchanged but any attempts to update them must align with this definition.

Arguments

Anchor to definitiondefinition •MetafieldDefinitionInput! required: Specifies the input fields for a metafield definition.

Was this section helpful?

Anchor to MetafieldDefinitionCreatePayload returnsMetafieldDefinitionCreatePayload returns

Anchor to createdDefinitioncreatedDefinition •MetafieldDefinition: The metafield definition that was created.
Anchor to userErrorsuserErrors •[MetafieldDefinitionCreateUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create a metafield definition

Description

You can create a metafield definition using the `metafieldDefinitionCreate` mutation. The following example shows how to add a metafield definition called "Ingredients" to the Product resource, which stores multi-line text (such as a list of ingredients used to make the product).

Query

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      name
    }
    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"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } 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"
    }
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      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"
      }
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

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

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          name
        }
        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"
      }
    },
  },
});

Response

{
  "metafieldDefinitionCreate": {
    "createdDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456166",
      "name": "Ingredients"
    },
    "userErrors": []
  }
}

Create a metafield definition to be used with automated collections

Description

You can use metafield definitions as collection condition rules for automated collections. The first step is to enable the metafield definition `useAsCollectionCondition` flag. This flag can be activated on a maximum of 128 definitions per product and variant metafield defintions. Note that you cannot delete the metafield definition if it is being used as a collection condition rule.

Query

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      name
      useAsCollectionCondition
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "definition": {
    "name": "Material",
    "namespace": "custom",
    "key": "material",
    "description": "A list of materials used to make the product.",
    "type": "list.single_line_text_field",
    "ownerType": "PRODUCT",
    "useAsCollectionCondition": true
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name useAsCollectionCondition } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Material",
      "namespace": "custom",
      "key": "material",
      "description": "A list of materials used to make the product.",
      "type": "list.single_line_text_field",
      "ownerType": "PRODUCT",
      "useAsCollectionCondition": true
    }
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
        useAsCollectionCondition
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
      "definition": {
        "name": "Material",
        "namespace": "custom",
        "key": "material",
        "description": "A list of materials used to make the product.",
        "type": "list.single_line_text_field",
        "ownerType": "PRODUCT",
        "useAsCollectionCondition": true
      }
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
        useAsCollectionCondition
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Material",
    "namespace": "custom",
    "key": "material",
    "description": "A list of materials used to make the product.",
    "type": "list.single_line_text_field",
    "ownerType": "PRODUCT",
    "useAsCollectionCondition": true
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          name
          useAsCollectionCondition
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
      "definition": {
        "name": "Material",
        "namespace": "custom",
        "key": "material",
        "description": "A list of materials used to make the product.",
        "type": "list.single_line_text_field",
        "ownerType": "PRODUCT",
        "useAsCollectionCondition": true
      }
    },
  },
});

Response

{
  "metafieldDefinitionCreate": {
    "createdDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456167",
      "name": "Material",
      "useAsCollectionCondition": true
    },
    "userErrors": []
  }
}

Create a metafield definition with access controls

Description

The following example shows how to create a metafield definition in a namespace with a reserved prefix that is read- only to the merchant, grants explicit access to 2 specified apps, and no other app can access it via the Admin API.

Query

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
      access {
        admin
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "definition": {
    "name": "Pizza size",
    "namespace": "$app:bakery",
    "key": "pizza_size",
    "type": "dimension",
    "description": "The size (diameter) of the pizza in inches.",
    "ownerType": "PRODUCT",
    "access": {
      "admin": "MERCHANT_READ"
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id namespace access { admin } } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Pizza size",
      "namespace": "$app:bakery",
      "key": "pizza_size",
      "type": "dimension",
      "description": "The size (diameter) of the pizza in inches.",
      "ownerType": "PRODUCT",
      "access": {
        "admin": "MERCHANT_READ"
      }
    }
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        namespace
        access {
          admin
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
      "definition": {
        "name": "Pizza size",
        "namespace": "$app:bakery",
        "key": "pizza_size",
        "type": "dimension",
        "description": "The size (diameter) of the pizza in inches.",
        "ownerType": "PRODUCT",
        "access": {
          "admin": "MERCHANT_READ"
        }
      }
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        namespace
        access {
          admin
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Pizza size",
    "namespace": "$app:bakery",
    "key": "pizza_size",
    "type": "dimension",
    "description": "The size (diameter) of the pizza in inches.",
    "ownerType": "PRODUCT",
    "access": {
      "admin": "MERCHANT_READ"
    }
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          namespace
          access {
            admin
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
      "definition": {
        "name": "Pizza size",
        "namespace": "$app:bakery",
        "key": "pizza_size",
        "type": "dimension",
        "description": "The size (diameter) of the pizza in inches.",
        "ownerType": "PRODUCT",
        "access": {
          "admin": "MERCHANT_READ"
        }
      }
    },
  },
});

Response

{
  "metafieldDefinitionCreate": {
    "createdDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456164",
      "namespace": "app--23898054--bakery",
      "access": {
        "admin": "MERCHANT_READ"
      }
    },
    "userErrors": []
  }
}

Create a metafield definition with validations

Description

The following example shows how to create a metafield definition called `Pizza size` with a `minimum` size of 9 and a `maximum` size of 15.

Query

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      name
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "definition": {
    "name": "Pizza size",
    "namespace": "bakery",
    "key": "pizza_size",
    "type": "dimension",
    "description": "The size (diameter) of the pizza in inches.",
    "validations": [
      {
        "name": "min",
        "value": "{\"unit\": \"INCHES\", \"value\": \"9\"}"
      },
      {
        "name": "max",
        "value": "{\"unit\": \"INCHES\", \"value\": \"15\"}"
      }
    ],
    "ownerType": "PRODUCT"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Pizza size",
      "namespace": "bakery",
      "key": "pizza_size",
      "type": "dimension",
      "description": "The size (diameter) of the pizza in inches.",
      "validations": [
        {
          "name": "min",
          "value": "{\"unit\": \"INCHES\", \"value\": \"9\"}"
        },
        {
          "name": "max",
          "value": "{\"unit\": \"INCHES\", \"value\": \"15\"}"
        }
      ],
      "ownerType": "PRODUCT"
    }
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
      "definition": {
        "name": "Pizza size",
        "namespace": "bakery",
        "key": "pizza_size",
        "type": "dimension",
        "description": "The size (diameter) of the pizza in inches.",
        "validations": [
          {
            "name": "min",
            "value": "{\"unit\": \"INCHES\", \"value\": \"9\"}"
          },
          {
            "name": "max",
            "value": "{\"unit\": \"INCHES\", \"value\": \"15\"}"
          }
        ],
        "ownerType": "PRODUCT"
      }
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Pizza size",
    "namespace": "bakery",
    "key": "pizza_size",
    "type": "dimension",
    "description": "The size (diameter) of the pizza in inches.",
    "validations": [{"name"=>"min", "value"=>"{\"unit\": \"INCHES\", \"value\": \"9\"}"}, {"name"=>"max", "value"=>"{\"unit\": \"INCHES\", \"value\": \"15\"}"}],
    "ownerType": "PRODUCT"
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          name
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
      "definition": {
        "name": "Pizza size",
        "namespace": "bakery",
        "key": "pizza_size",
        "type": "dimension",
        "description": "The size (diameter) of the pizza in inches.",
        "validations": [
          {
            "name": "min",
            "value": "{\"unit\": \"INCHES\", \"value\": \"9\"}"
          },
          {
            "name": "max",
            "value": "{\"unit\": \"INCHES\", \"value\": \"15\"}"
          }
        ],
        "ownerType": "PRODUCT"
      }
    },
  },
});

Response

{
  "metafieldDefinitionCreate": {
    "createdDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456165",
      "name": "Pizza size"
    },
    "userErrors": []
  }
}

metafieldDefinitionCreate reference

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {

metafieldDefinitionCreate(definition: $definition) {

createdDefinition {

name

}

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"

}

);

const data = await response.json();

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      name
    }
    userErrors {
      field
      message
      code
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } 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"
    }
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      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"
      }
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          name
        }
        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"
      }
    },
  },
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

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

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"definition": {

"name": "Ingredients",

"namespace": "bakery",

"key": "ingredients",

"description": "A list of ingredients used to make the product.",

"type": "multi_line_text_field",

"ownerType": "PRODUCT"

}

Response

JSON

{

"metafieldDefinitionCreate": {

"createdDefinition": {

"id": "gid://shopify/MetafieldDefinition/1071456166",

"name": "Ingredients"

"userErrors": []

}