Are metafieldDefinitionPin arguments correct in API docs?

Technical Q&A

Topic summary

The API documentation for metafieldDefinitionPin appears to contain contradictory information:

The Issue:

  • Documentation lists identifier as the only argument
  • Shows definitionId as deprecated
  • However, the code example uses definitionId
  • Attempting to use identifier (as documented) produces errors

Error Messages Received:

  • “Field ‘metafieldDefinitionPin’ doesn’t accept ‘identifier’ argument”
  • “Field ‘metafieldDefinitionPin’ is missing required arguments: definitionId”

Question Raised:
Was the wrong argument marked as deprecated in the documentation? The practical implementation contradicts the stated API specification, suggesting a documentation error that needs clarification from Shopify.

Summarized with AI on November 3. AI used: claude-sonnet-4-5-20250929.
1

https://shopify.dev/docs/api/admin-graphql/unstable/mutations/metafielddefinitionpin

Shows identifier as only argument, and definitionId as deprecated. Yet, the code example shows definitionId, and trying to use identifier gives the below errors. So err… are the docs wrong? Did someone tag the wrong argument as deprecated?

   "message": "Field 'metafieldDefinitionPin' is missing required arguments: definitionId",

"message": "Field 'metafieldDefinitionPin' doesn't accept argument 'identifier'",

{% action “shopify” %}
mutation {
metafieldDefinitionPin (
identifier: {
namespace: “MY_NAMESPACE”,
key: “MY_KEY”,
ownerType: PRODUCTVARIANT
}
) {
pinnedDefinition {
name
key
namespace
pinnedPosition
}
}
}
{% endaction %}