metafieldDefinitionCreate - admin-graphql - MUTATION

Version: 2025-01

Description:

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.

Access Scopes

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

Arguments

• definition: MetafieldDefinitionInput! - Specifies the input fields for a metafield definition.

Returns

• createdDefinition: MetafieldDefinition The metafield definition that was created.
• userErrors: MetafieldDefinitionCreateUserError! The list of errors that occurred from executing the mutation.

Examples

• Create a metafield definition

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Ingredients\",\n      \"namespace\": \"bakery\",\n      \"key\": \"ingredients\",\n      \"description\": \"A list of ingredients used to make the product.\",\n      \"type\": \"multi_line_text_field\",\n      \"ownerType\": \"PRODUCT\"\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n      metafieldDefinitionCreate(definition: $definition) {\n        createdDefinition {\n          id\n          name\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Ingredients\",\n        \"namespace\": \"bakery\",\n        \"key\": \"ingredients\",\n        \"description\": \"A list of ingredients used to make the product.\",\n        \"type\": \"multi_line_text_field\",\n        \"ownerType\": \"PRODUCT\"\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Ingredients\",\n    \"namespace\": \"bakery\",\n    \"key\": \"ingredients\",\n    \"description\": \"A list of ingredients used to make the product.\",\n    \"type\": \"multi_line_text_field\",\n    \"ownerType\": \"PRODUCT\"\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Ingredients\",\n    \"namespace\" => \"bakery\",\n    \"key\" => \"ingredients\",\n    \"description\" => \"A list of ingredients used to make the product.\",\n    \"type\" => \"multi_line_text_field\",\n    \"ownerType\" => \"PRODUCT\",\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Ingredients\",\n        \"namespace\": \"bakery\",\n        \"key\": \"ingredients\",\n        \"description\": \"A list of ingredients used to make the product.\",\n        \"type\": \"multi_line_text_field\",\n        \"ownerType\": \"PRODUCT\"\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n  metafieldDefinitionCreate(definition: $definition) {\n    createdDefinition {\n      id\n      name\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "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: {
    "data": {
      "metafieldDefinitionCreate": {
        "createdDefinition": {
          "id": "gid://shopify/MetafieldDefinition/1071456166",
          "name": "Ingredients"
        },
        "userErrors": []
      }
    }
  }

  Create a metafield definition to be used with automated collections

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name useAsCollectionCondition } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Material\",\n      \"namespace\": \"custom\",\n      \"key\": \"material\",\n      \"description\": \"A list of materials used to make the product.\",\n      \"type\": \"list.single_line_text_field\",\n      \"ownerType\": \"PRODUCT\",\n      \"useAsCollectionCondition\": true\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n      metafieldDefinitionCreate(definition: $definition) {\n        createdDefinition {\n          id\n          name\n          useAsCollectionCondition\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Material\",\n        \"namespace\": \"custom\",\n        \"key\": \"material\",\n        \"description\": \"A list of materials used to make the product.\",\n        \"type\": \"list.single_line_text_field\",\n        \"ownerType\": \"PRODUCT\",\n        \"useAsCollectionCondition\": true\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n        useAsCollectionCondition\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Material\",\n    \"namespace\": \"custom\",\n    \"key\": \"material\",\n    \"description\": \"A list of materials used to make the product.\",\n    \"type\": \"list.single_line_text_field\",\n    \"ownerType\": \"PRODUCT\",\n    \"useAsCollectionCondition\": true\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n        useAsCollectionCondition\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Material\",\n    \"namespace\" => \"custom\",\n    \"key\" => \"material\",\n    \"description\" => \"A list of materials used to make the product.\",\n    \"type\" => \"list.single_line_text_field\",\n    \"ownerType\" => \"PRODUCT\",\n    \"useAsCollectionCondition\" => true,\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n        useAsCollectionCondition\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Material\",\n        \"namespace\": \"custom\",\n        \"key\": \"material\",\n        \"description\": \"A list of materials used to make the product.\",\n        \"type\": \"list.single_line_text_field\",\n        \"ownerType\": \"PRODUCT\",\n        \"useAsCollectionCondition\": true\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n  metafieldDefinitionCreate(definition: $definition) {\n    createdDefinition {\n      id\n      name\n      useAsCollectionCondition\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "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: {
    "data": {
      "metafieldDefinitionCreate": {
        "createdDefinition": {
          "id": "gid://shopify/MetafieldDefinition/1071456167",
          "name": "Material",
          "useAsCollectionCondition": true
        },
        "userErrors": []
      }
    }
  }

  Create a metafield definition with access controls

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id namespace access { admin } } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Pizza size\",\n      \"namespace\": \"$app:bakery\",\n      \"key\": \"pizza_size\",\n      \"type\": \"dimension\",\n      \"description\": \"The size (diameter) of the pizza in inches.\",\n      \"ownerType\": \"PRODUCT\",\n      \"access\": {\n        \"admin\": \"MERCHANT_READ\"\n      }\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n      metafieldDefinitionCreate(definition: $definition) {\n        createdDefinition {\n          id\n          namespace\n          access {\n            admin\n          }\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Pizza size\",\n        \"namespace\": \"$app:bakery\",\n        \"key\": \"pizza_size\",\n        \"type\": \"dimension\",\n        \"description\": \"The size (diameter) of the pizza in inches.\",\n        \"ownerType\": \"PRODUCT\",\n        \"access\": {\n          \"admin\": \"MERCHANT_READ\"\n        }\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        namespace\n        access {\n          admin\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Pizza size\",\n    \"namespace\": \"$app:bakery\",\n    \"key\": \"pizza_size\",\n    \"type\": \"dimension\",\n    \"description\": \"The size (diameter) of the pizza in inches.\",\n    \"ownerType\": \"PRODUCT\",\n    \"access\": {\n      \"admin\": \"MERCHANT_READ\"\n    }\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        namespace\n        access {\n          admin\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Pizza size\",\n    \"namespace\" => \"$app:bakery\",\n    \"key\" => \"pizza_size\",\n    \"type\" => \"dimension\",\n    \"description\" => \"The size (diameter) of the pizza in inches.\",\n    \"ownerType\" => \"PRODUCT\",\n    \"access\" => [\n      \"admin\" => \"MERCHANT_READ\",\n    ],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        namespace\n        access {\n          admin\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Pizza size\",\n        \"namespace\": \"$app:bakery\",\n        \"key\": \"pizza_size\",\n        \"type\": \"dimension\",\n        \"description\": \"The size (diameter) of the pizza in inches.\",\n        \"ownerType\": \"PRODUCT\",\n        \"access\": {\n          \"admin\": \"MERCHANT_READ\"\n        }\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n  metafieldDefinitionCreate(definition: $definition) {\n    createdDefinition {\n      id\n      namespace\n      access {\n        admin\n      }\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "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: {
    "data": {
      "metafieldDefinitionCreate": {
        "createdDefinition": {
          "id": "gid://shopify/MetafieldDefinition/1071456164",
          "namespace": "app--23898054--bakery",
          "access": {
            "admin": "MERCHANT_READ"
          }
        },
        "userErrors": []
      }
    }
  }

  Create a metafield definition with validations

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Pizza size\",\n      \"namespace\": \"bakery\",\n      \"key\": \"pizza_size\",\n      \"type\": \"dimension\",\n      \"description\": \"The size (diameter) of the pizza in inches.\",\n      \"validations\": [\n        {\n          \"name\": \"min\",\n          \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"9\\\"}\"\n        },\n        {\n          \"name\": \"max\",\n          \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"15\\\"}\"\n        }\n      ],\n      \"ownerType\": \"PRODUCT\"\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n      metafieldDefinitionCreate(definition: $definition) {\n        createdDefinition {\n          id\n          name\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Pizza size\",\n        \"namespace\": \"bakery\",\n        \"key\": \"pizza_size\",\n        \"type\": \"dimension\",\n        \"description\": \"The size (diameter) of the pizza in inches.\",\n        \"validations\": [\n          {\n            \"name\": \"min\",\n            \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"9\\\"}\"\n          },\n          {\n            \"name\": \"max\",\n            \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"15\\\"}\"\n          }\n        ],\n        \"ownerType\": \"PRODUCT\"\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Pizza size\",\n    \"namespace\": \"bakery\",\n    \"key\": \"pizza_size\",\n    \"type\": \"dimension\",\n    \"description\": \"The size (diameter) of the pizza in inches.\",\n    \"validations\": [{\"name\"=>\"min\", \"value\"=>\"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"9\\\"}\"}, {\"name\"=>\"max\", \"value\"=>\"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"15\\\"}\"}],\n    \"ownerType\": \"PRODUCT\"\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Pizza size\",\n    \"namespace\" => \"bakery\",\n    \"key\" => \"pizza_size\",\n    \"type\" => \"dimension\",\n    \"description\" => \"The size (diameter) of the pizza in inches.\",\n    \"validations\" => [{\"name\"=>\"min\", \"value\"=>\"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"9\\\"}\"}, {\"name\"=>\"max\", \"value\"=>\"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"15\\\"}\"}],\n    \"ownerType\" => \"PRODUCT\",\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n    metafieldDefinitionCreate(definition: $definition) {\n      createdDefinition {\n        id\n        name\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Pizza size\",\n        \"namespace\": \"bakery\",\n        \"key\": \"pizza_size\",\n        \"type\": \"dimension\",\n        \"description\": \"The size (diameter) of the pizza in inches.\",\n        \"validations\": [\n          {\n            \"name\": \"min\",\n            \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"9\\\"}\"\n          },\n          {\n            \"name\": \"max\",\n            \"value\": \"{\\\"unit\\\": \\\"INCHES\\\", \\\"value\\\": \\\"15\\\"}\"\n          }\n        ],\n        \"ownerType\": \"PRODUCT\"\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {\n  metafieldDefinitionCreate(definition: $definition) {\n    createdDefinition {\n      id\n      name\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "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: {
    "data": {
      "metafieldDefinitionCreate": {
        "createdDefinition": {
          "id": "gid://shopify/MetafieldDefinition/1071456165",
          "name": "Pizza size"
        },
        "userErrors": []
      }
    }
  }