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?

Create a metafield definition
Create a metafield definition to be used with automated collections
Create a metafield definition with access controls
Create a metafield definition with validations
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": []

}