# 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](/docs/api/admin-graphql/2025-01/input-objects/MetafieldDefinitionInput): MetafieldDefinitionInput! - Specifies the input fields for a metafield definition. ## Returns * [createdDefinition](/docs/api/admin-graphql/2025-01/objects/MetafieldDefinition): MetafieldDefinition The metafield definition that was created. * [userErrors](/docs/api/admin-graphql/2025-01/objects/MetafieldDefinitionCreateUserError): 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" 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}" #### Graphql 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" } } #### Graphql 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" 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}" #### Graphql 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 } } #### Graphql 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" 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}" #### Graphql 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" } } } #### Graphql 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" 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}" #### Graphql 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" } } #### Graphql Response { "data": { "metafieldDefinitionCreate": { "createdDefinition": { "id": "gid://shopify/MetafieldDefinition/1071456165", "name": "Pizza size" }, "userErrors": [] } } }