Unable to Update shopify Namespace Metafield Definition Constraints via API (ACCESS_DENIED Error)

Custom Data
1

Hi all,

I’m running into an issue when trying to update the constraints of a metafield definition with the namespace shopify. Specifically, I’m attempting to update the category key of the shopify.color-pattern metafield definition (ownerType: PRODUCT).

Here’s the mutation I’m using:

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

Variables:

{
  "definition": {
    "namespace": "shopify",
    "key": "color-pattern",
    "ownerType": "PRODUCT",
    "constraintsUpdates": {
      "key": "category",
      "values": [{ "create": "aa-1-6-11-4" }]
    }
  }
}

Error received:

{
  "errors": [
    {
      "message": "Access denied for metafieldDefinitionUpdate field. Required access: API client to have access to the namespace and the resource type associated with the metafield definition.",
      "extensions": {
        "code": "ACCESS_DENIED",
        "documentation": "https://shopify.dev/api/usage/access-scopes",
        "requiredAccess": "API client to have access to the namespace and the resource type associated with the metafield definition."
      }
    }
  ],
  "data": {
    "metafieldDefinitionUpdate": null
  }
}

When I run the same mutation for a custom metafield definition (for example, namespace test_data, key snowboard_length), it works fine:

    "metafieldDefinitionUpdate": {
      "updatedDefinition": {
        "id": "gid://shopify/MetafieldDefinition/98592456809",
        "name": "Snowboard length",
        "constraints": {
          "key": "category",
          "values": {
            "nodes": [
              {
                "value": "aa-1-6-11-4"
              }
            ]
          }
        }
      },
      "userErrors": []
    }
  },

Interestingly, if I go into Settings > Metafields and Metaobjects > Product metafield definitions > Assigned to categories > Color (shopify.color-pattern), I can manually edit the category assignments:

image
image1443×788 77.9 KB

Question:

  • Is it possible to update the constraints (category assignments) for shopify namespace metafields programmatically from an app?

  • Or is this restricted so that it can only be done through the Shopify Admin settings UI?

Environment details:

  • Public embedded app using the shopify app node template

  • Scopes:

[access_scopes]
scopes = "read_products,write_products,read_metaobject_definitions,read_metaobjects,write_metaobjects,write_metaobject_definitions"
  • API Version: 2025-10
  • Running mutation via local dev server GraphiQL (http://localhost:3457/graphiql)
  • The app is installed on a dev store

Any guidance on whether this is an intentional limitation, or if there’s a required access scope I might be missing, would be much appreciated!