Choose a version:

metafieldDefinition

query

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

Retrieves a MetafieldDefinition by its identifier. You can identify a definition using either its owner type, namespace, and key, or its global ID.

Use this query to inspect a definition's configuration, including its data type, validations, access settings, and the count of metafields using it.

Anchor to Arguments

Arguments

Anchor to identifieridentifier

•MetafieldDefinitionIdentifierInput

The identifier of the MetafieldDefinition to return.

Anchor to idid

•ID

Deprecated

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to MetafieldDefinitionMetafieldDefinition

•MetafieldDefinition

Defines the structure, validation rules, and permissions for Metafield objects attached to a specific owner type. Each definition establishes a schema that metafields must follow, including the data type and validation constraints.

The definition controls access permissions across different APIs, determines whether the metafield can be used for filtering or as a collection condition, and can be constrained to specific resource subtypes.

Anchor to accessaccess

•MetafieldAccess!

non-null

The access settings associated with the metafield definition.

Anchor to capabilitiescapabilities

•MetafieldCapabilities!

non-null

The capabilities of the metafield definition.

Anchor to constraintsconstraints

•MetafieldDefinitionConstraints

The constraints that determine what subtypes of resources a metafield definition applies to.

Anchor to descriptiondescription

•String

The description of the metafield definition.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to keykey

•String!

non-null

The unique identifier for the metafield definition within its namespace.

Anchor to metafieldsmetafields

•MetafieldConnection!

non-null

The metafields that belong to the metafield definition.

Arguments

Anchor to validationStatusvalidationStatus

•MetafieldValidationStatus

Default:ANY

Returns the metafields filtered by the validation status.

Anchor to firstfirst

•Int

The first n elements from the paginated list.

Anchor to afterafter

•String

The elements that come after the specified cursor.

Anchor to lastlast

•Int

The last n elements from the paginated list.

Anchor to beforebefore

•String

The elements that come before the specified cursor.

Anchor to reversereverse

•Boolean

Default:false

Reverse the order of the underlying list.

Anchor to metafieldsCountmetafieldsCount

•Int!

non-null

The count of the metafields that belong to the metafield definition.

Arguments

Anchor to validationStatusvalidationStatus

•MetafieldValidationStatus

The current validation status.

Anchor to namename

•String!

non-null

The human-readable name of the metafield definition.

Anchor to namespacenamespace

•String!

non-null

The container for a group of metafields that the metafield definition is associated with.

Anchor to ownerTypeownerType

•MetafieldOwnerType!

non-null

The resource type that the metafield definition is attached to.

Anchor to pinnedPositionpinnedPosition

•Int

The position of the metafield definition in the pinned list.

Anchor to standardTemplatestandardTemplate

•StandardMetafieldDefinitionTemplate

The standard metafield definition template associated with the metafield definition.

Anchor to typetype

•MetafieldDefinitionType!

non-null

The type of data that each of the metafields that belong to the metafield definition will store. Refer to the list of supported types.

Anchor to useAsCollectionConditionuseAsCollectionCondition

•Boolean!

non-null

Whether the metafield definition can be used as a collection condition.

Anchor to validationsvalidations

•[MetafieldDefinitionValidation!]!

non-null

A list of validation options for the metafields that belong to the metafield definition. For example, for a metafield definition with the type date, you can set a minimum date validation so that each of the metafields that belong to it can only store dates after the specified minimum.

Anchor to validationStatusvalidationStatus

•MetafieldDefinitionValidationStatus!

non-null

The validation status for the metafields that belong to the metafield definition.

Was this section helpful?

Examples

Retrieve a count of a resource's metafields.

Query

query MetafieldsCount($metafieldDefinitionId: ID!) {
  metafieldDefinition(id: $metafieldDefinitionId) {
    id
    metafieldsCount
  }
}

Variables

{
  "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetafieldsCount($metafieldDefinitionId: ID!) { metafieldDefinition(id: $metafieldDefinitionId) { id metafieldsCount } }",
 "variables": {
    "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }`,
  {
    variables: {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
  );
  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
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }
QUERY

variables = {
  "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query MetafieldsCount($metafieldDefinitionId: ID!) {
      metafieldDefinition(id: $metafieldDefinitionId) {
        id
        metafieldsCount
      }
    }`,
    "variables": {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
});

Response

{
  "metafieldDefinition": {
    "id": "gid://shopify/MetafieldDefinition/1071456212",
    "metafieldsCount": 0
  }
}

Retrieve a metafield definition

Description

To retrieve a single metafield definition, use the `metafieldDefinition` query with its ID. The following example shows how to retrieve a metafield definition.

Query

query {
  metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
    name
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { metafieldDefinition(id: \"gid://shopify/MetafieldDefinition/1071456211\") { name } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
      name
    }
  }`,
  );
  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
  query {
    metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
      name
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
      name
    }
  }`,
});

Response

{
  "metafieldDefinition": {
    "name": "ingredients"
  }
}

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

query MetafieldsCount($metafieldDefinitionId: ID!) {

metafieldDefinition(id: $metafieldDefinitionId) {

metafieldsCount

}

}`,

{

variables: {

"metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"

);

const json = await response.json();

return json.data;

}

GQL

query MetafieldsCount($metafieldDefinitionId: ID!) {
  metafieldDefinition(id: $metafieldDefinitionId) {
    id
    metafieldsCount
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetafieldsCount($metafieldDefinitionId: ID!) { metafieldDefinition(id: $metafieldDefinitionId) { id metafieldsCount } }",
 "variables": {
    "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }`,
  {
    variables: {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query MetafieldsCount($metafieldDefinitionId: ID!) {
      metafieldDefinition(id: $metafieldDefinitionId) {
        id
        metafieldsCount
      }
    }`,
    "variables": {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
});

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
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }
QUERY

variables = {
  "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
}

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

Input variables

JSON

{

"metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"

}

Response

JSON

{

"metafieldDefinition": {

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

"metafieldsCount": 0

}