Skip to main content

Why can't I create Metaobject reference, Mixed reference, or ID custom fields?

When adding a field to a metafield set, you'll notice that Metaobject reference, Mixed reference, and ID are greyed out in the type selector and can't be created as custom fields. This isn't a restriction we've added on our end – it comes directly from how Shopify treats these three metafield types.

Shopify requires a definition to exist first​

Most metafield types (text, number, date, boolean, and so on) are self-descriptive: Shopify knows how to validate and store a value the moment you write it, no extra setup required. These three types don't work that way:

  • Metaobject reference and Mixed reference need to know, in advance, which metaobject entries a value is allowed to point to. For example, a "Product highlights" reference field might only be allowed to link to entries from your "Highlight" metaobject, or - for a mixed reference - to entries from either "Highlight" or "Supplier". That rule isn't part of the value itself, it only exists on the metafield definition. Without a definition referencing a metaobject this way, Shopify has nothing to check the value against.
  • ID is a special type meant for storing a unique external identifier, for example, so you can match a product or customer to a record in another system (an ERP, CRM, or PIM). Shopify automatically enforces that every value of this type is unique, and that check is set up on the metafield definition – so the definition has to exist before any value can be saved.

In short: Shopify itself won't let you save a value of these types unless a matching metafield definition already exists. Offering them as "custom fields" - metafields created and managed without a definition - would just fail when you tried to save data, so there's no point in offering that option.

What to do instead​

Metafield sets support Shopify metafield definitions natively, so you attach the definition to your set instead of creating a custom field:

  • If you don't have a matching definition yet, create one either in your store's Shopify admin, or right on the set page in our app by clicking the Add definition button.
  • If a matching definition already exists, click Select existing on the set page and pick it from the list.

Attaching the definition directly, rather than proxying it through a custom field, also keeps your set and your Shopify schema in sync: there's a single source of truth for the type, validation rules, and (for references) the allowed metaobject definitions, instead of two configurations that could drift apart.

A bit of history

Metaobject reference, Mixed reference, and ID used to be selectable as custom fields in older versions of the app. Our metafield sets were built before Shopify introduced metafield definitions, and our original data structure had no way to attach a definition to a set directly – creating these fields as custom fields was a workaround to get them into a set at all. Since we've since moved to a newer, more flexible data structure that supports attaching definitions directly, that workaround is no longer needed, which is why it's been retired.