Choose a version:

metafieldDefinitionUpdate

mutation

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

Updates a MetafieldDefinition's configuration and settings. You can modify the definition's name, description, validation rules, access settings, capabilities, and constraints.

The mutation updates access settings that control visibility across different APIs, such as the GraphQL Admin API, Storefront API, and Customer Account API. It also enables capabilities like admin filtering or unique value validation, and modifies constraints that determine which resource subtypes the definition applies to.

Note

The type, namespace, key, and owner type identify the definition and so can't be changed.

Learn more about updating metafield definitions.

Anchor to Arguments

Arguments

Anchor to definitiondefinition •MetafieldDefinitionUpdateInput! required: The input fields for the metafield definition update.

Was this section helpful?

Anchor to MetafieldDefinitionUpdatePayload returnsMetafieldDefinitionUpdatePayload returns

Anchor to updatedDefinitionupdatedDefinition •MetafieldDefinition: The metafield definition that was updated.
Anchor to userErrorsuserErrors •[MetafieldDefinitionUpdateUserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to validationJobvalidationJob •Job: The asynchronous job updating the metafield definition's validation_status.

Was this section helpful?

Examples

Update a metafield definition

Description

To update a metafield definition, use the `metafieldDefinitionUpdate` mutation. The following example shows how to change a metafield definition's name from `Pizza size` to `Pizza size (inches)`.

Query

mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
  metafieldDefinitionUpdate(definition: $definition) {
    updatedDefinition {
      id
      name
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) { metafieldDefinitionUpdate(definition: $definition) { updatedDefinition { id name } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Pizza size (inches)",
      "namespace": "bakery",
      "key": "pizza_size",
      "ownerType": "PRODUCT"
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Pizza size (inches)",
    "namespace": "bakery",
    "key": "pizza_size",
    "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 UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
      metafieldDefinitionUpdate(definition: $definition) {
        updatedDefinition {
          id
          name
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT"
        }
    },
  },
});

Response

{
  "metafieldDefinitionUpdate": {
    "updatedDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456170",
      "name": "Pizza size (inches)"
    },
    "userErrors": []
  }
}

Update a metafield definition with access controls

Description

To change the access settings on an existing definition, use the `access` property in your `metafieldDefinitionUpdate` mutation. You can set the default admin access setting and also specify additional grants to create, update or delete.

Query

mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
  metafieldDefinitionUpdate(definition: $definition) {
    updatedDefinition {
      id
      name
      access {
        admin
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "definition": {
    "name": "Pizza size (inches)",
    "namespace": "$app:bakery",
    "key": "pizza_size",
    "ownerType": "PRODUCT",
    "access": {
      "admin": "PRIVATE"
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) { metafieldDefinitionUpdate(definition: $definition) { updatedDefinition { id name access { admin } } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Pizza size (inches)",
      "namespace": "$app:bakery",
      "key": "pizza_size",
      "ownerType": "PRODUCT",
      "access": {
        "admin": "PRIVATE"
      }
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
        access {
          admin
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "$app:bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT",
            "access": {
                "admin": "PRIVATE"
            }
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
        access {
          admin
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Pizza size (inches)",
    "namespace": "$app:bakery",
    "key": "pizza_size",
    "ownerType": "PRODUCT",
    "access": {
      "admin": "PRIVATE"
    }
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
      metafieldDefinitionUpdate(definition: $definition) {
        updatedDefinition {
          id
          name
          access {
            admin
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "$app:bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT",
            "access": {
                "admin": "PRIVATE"
            }
        }
    },
  },
});

Response

{
  "metafieldDefinitionUpdate": {
    "updatedDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456171",
      "name": "Pizza size (inches)",
      "access": {
        "admin": "PRIVATE"
      }
    },
    "userErrors": []
  }
}

metafieldDefinitionUpdate reference

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

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

const response = await admin.graphql(

`#graphql

mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {

metafieldDefinitionUpdate(definition: $definition) {

updatedDefinition {

name

}

userErrors {

field

message

code

}

}`,

{

variables: {

"definition": {

"name": "Pizza size (inches)",

"namespace": "bakery",

"key": "pizza_size",

"ownerType": "PRODUCT"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
  metafieldDefinitionUpdate(definition: $definition) {
    updatedDefinition {
      id
      name
    }
    userErrors {
      field
      message
      code
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) { metafieldDefinitionUpdate(definition: $definition) { updatedDefinition { id name } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Pizza size (inches)",
      "namespace": "bakery",
      "key": "pizza_size",
      "ownerType": "PRODUCT"
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
      metafieldDefinitionUpdate(definition: $definition) {
        updatedDefinition {
          id
          name
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "definition": {
            "name": "Pizza size (inches)",
            "namespace": "bakery",
            "key": "pizza_size",
            "ownerType": "PRODUCT"
        }
    },
  },
});

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 UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
    metafieldDefinitionUpdate(definition: $definition) {
      updatedDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

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

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

Input variables

JSON

{

"definition": {

"name": "Pizza size (inches)",

"namespace": "bakery",

"key": "pizza_size",

"ownerType": "PRODUCT"

}

Response

JSON

{

"metafieldDefinitionUpdate": {

"updatedDefinition": {

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

"name": "Pizza size (inches)"

"userErrors": []

}