metafieldDefinitionPin

mutation

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

You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed.

Arguments

Anchor to definitionIddefinitionId • ID: The id of the metafield definition to pin. Using identifier is preferred.
Anchor to identifieridentifier • MetafieldDefinitionIdentifierInput: The identifier of the metafield definition to pin.

Was this section helpful?

Anchor to MetafieldDefinitionPinPayload returnsMetafieldDefinitionPinPayload returns

Anchor to pinnedDefinitionpinnedDefinition • MetafieldDefinition: The metafield definition that was pinned.
Anchor to userErrorsuserErrors • [MetafieldDefinitionPinUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Pin a metafield definition
metafieldDefinitionPin reference

Examples

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

const response = await admin.graphql(

`#graphql

mutation metafieldDefinitionPin($definitionId: ID!) {

metafieldDefinitionPin(definitionId: $definitionId) {

pinnedDefinition {

name

key

namespace

pinnedPosition

}

userErrors {

field

message

}

}`,

{

variables: {

"definitionId": "gid://shopify/MetafieldDefinition/1071456171"

);

const data = await response.json();

mutation metafieldDefinitionPin($definitionId: ID!) {
  metafieldDefinitionPin(definitionId: $definitionId) {
    pinnedDefinition {
      name
      key
      namespace
      pinnedPosition
    }
    userErrors {
      field
      message
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation metafieldDefinitionPin($definitionId: ID!) { metafieldDefinitionPin(definitionId: $definitionId) { pinnedDefinition { name key namespace pinnedPosition } userErrors { field message } } }",
 "variables": {
    "definitionId": "gid://shopify/MetafieldDefinition/1071456171"
  }
}'

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

const response = await admin.graphql(
  `#graphql
  mutation metafieldDefinitionPin($definitionId: ID!) {
    metafieldDefinitionPin(definitionId: $definitionId) {
      pinnedDefinition {
        name
        key
        namespace
        pinnedPosition
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
      "definitionId": "gid://shopify/MetafieldDefinition/1071456171"
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation metafieldDefinitionPin($definitionId: ID!) {
      metafieldDefinitionPin(definitionId: $definitionId) {
        pinnedDefinition {
          name
          key
          namespace
          pinnedPosition
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
      "definitionId": "gid://shopify/MetafieldDefinition/1071456171"
    },
  },
});

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 metafieldDefinitionPin($definitionId: ID!) {
    metafieldDefinitionPin(definitionId: $definitionId) {
      pinnedDefinition {
        name
        key
        namespace
        pinnedPosition
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "definitionId": "gid://shopify/MetafieldDefinition/1071456171"
}

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

Input variables

JSON

{

"definitionId": "gid://shopify/MetafieldDefinition/1071456171"

}

Response

JSON

{

"metafieldDefinitionPin": {

"pinnedDefinition": {

"name": "Instructions to wash your product",

"key": "wash",

"namespace": "instructions",

"pinnedPosition": 1

"userErrors": []

}