Metafield definition cannot be pinned

GraphQL Admin API Troubleshooting
1

Hi there,

As part of a custom app on a merchant’s Plus account, we have published a metafield definition through the apps shopify.app.toml

But through the Shopify Admin, I cannot pin this custom order metafield to the dashboard.

This is a bit of a problem, because the staff need to be able to easily view this critical data, but the only error I see is “This metafield definition can’t be pinned”. There is no other detail explaining why.

Any workarounds to this?

CleanShot 2026-06-01 at 12.15.55@2x
CleanShot 2026-06-01 at 12.15.55@2x596×214 12.9 KB

2

No work around - but definitely want to add a big +1 from us! AFAIK, this is the current expected behaviour - app owned metafields can’t be pinned.

3

Actually two different workarounds here:

  1. It’s possible to pin a app reserved metafield definition for the table view using the ‘pin’ icon, even though it can’t be pinned from the actual definition details page
    brett-legacy-prod · Metafie...
  2. You can pin a metafield definition through the Admin GraphQL, so you could either have your app automatically pin definitions if universally relevant, or have an in-app function to allow merchants to pin certain definitions as desired
    metafieldDefinitionUpdate - GraphQL Admin
4

I don’t believe that’s accurate @Brett:

CleanShot 2026-06-01 at 23.25.28@2x
CleanShot 2026-06-01 at 23.25.28@2x1606×588 24.8 KB

When the definition is created via the toml - you can’ t use the admin graphql to update it either!

5

Ah gotcha. I glossed over the potential differences in toml defined here. We use lots of app reserved metafields but mostly through Admin GraphQL which seems like a significant difference in this context.

Apparently pinning toml definied definitions is specifically called out as a limitation, so you’re probably correct that there’s no workarounds.

6

So my workaround was to remove the .toml metafield definition. This way we could have a clean merchant managed metafield under the custom namespace.

Just feels brittle to reference a metafield in a extension’s code that doesn’t actually have a corresponding .toml definition for it.

So I guess now I know about this pinning limitation (or maybe it’s by design? Hard to tell).

But I know that merchants using my public apps would like to be able to pin app defined metafields, especially if they change some logic.