Link metafields to product options

Metafields are custom fields that store additional information about Shopify resources like products. Metaobjects are structured content entries that hold rich data—like color codes, taxonomy references, or custom attributes—and can be reused across products.

You can link metafields to product options to connect your products with Shopify's standardized product taxonomy. Instead of simple text values like "Red" or "Large", your options reference metaobjects that contain structured data, enabling features like improved search and marketplace integration.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the latest version of the GraphQL Admin API or higher.
• Your app has the write_products and write_metaobjects access scopes. Learn how to configure your access scopes using Shopify CLI.
• A metafield definition exists with owner type Product and type list.metaobject_reference (for example, custom.color-pattern).

Anchor to How it worksHow it works

Instead of using simple text for option values, you reference metaobjects that contain structured data. For example, instead of a color option with the text value "Red", you reference a metaobject that includes the color name, hex code, and taxonomy references.

First, you create metaobject entries for each option value (like creating an "Orange/Blue" color pattern metaobject). Then, you create products and reference those metaobjects in your options. The metaobject's display name becomes what customers see, while the structured data powers features like improved search and marketplace integration.

Anchor to Step 1: Create metaobject entriesStep 1: Create metaobject entries

Use metaobjectCreate to create metaobject entries that store structured data (like color names, hex codes, and taxonomy references) instead of simple text.

The following example creates an "Orange/Blue" color pattern using the custom--color-pattern definition:

Anchor to Step 2: Create the productStep 2: Create the product

Use productCreate to create a product with basic options. You'll add the linked option in the next step.

The following example creates a T-shirt with a Size option:

Anchor to Step 3: Add the linked optionStep 3: Add the linked option

Use productOptionsCreate to add a linked option to the product. The linkedMetafield field specifies which metafield definition to use, and linkedMetafieldValue references the metaobject ID from Step 1.

The following example adds a linked Color option:

Anchor to Step 4: Add values to an existing linked optionStep 4: Add values to an existing linked option

Use productOptionUpdate with optionValuesToAdd to add new linked values to an existing option.

The following example adds a "Red/White" color pattern. First create the metaobject entry (Step 1), then add it to the option. The new value has hasVariants: false until you create variants in Step 5.

Anchor to Step 5: Create variants for linked option valuesStep 5: Create variants for linked option values

After adding a new linked option value, create variants to make it purchasable. Use productVariantsBulkCreate with linkedMetafieldValue to reference the metaobject ID instead of a text name.

The following example creates two variants for the new "Red/White" color pattern, one for each size. The linkedMetafieldValue field references the metaobject, ensuring the variant is properly connected to the taxonomy data.

Anchor to Next stepsNext steps

• Learn more about metafields and metaobjects.
• Learn how to add product data.
• Explore the productOptionsCreate, productOptionUpdate, productVariantsBulkCreate, and metaobjectCreate mutations in the GraphQL Admin API reference.