--- title: Link metafields to product options description: >- Learn how to link metafields to product options for enhanced product taxonomy using the GraphQL Admin API. source_url: html: >- https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked md: >- https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#requirements) * [How it works](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#how-it-works) * [Step 1: Create metaobject entries](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-1-create-metaobject-entries) * [Step 2: Create the product](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-2-create-the-product) * [Step 3: Add the linked option](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-3-add-the-linked-option) * [Step 4: Add values to an existing linked option](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-4-add-values-to-an-existing-linked-option) * [Step 5: Create variants for linked option values](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-5-create-variants-for-linked-option-values) * [Next steps](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#next-steps) # 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. Note For standard product workflows without taxonomy, use regular options as shown in [Add product data](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/add-data). *** ## Requirements * Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the latest version of the GraphQL Admin API or higher. * Your app has the `write_products` and `write_metaobjects` [access scopes](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration). * A [metafield definition](https://shopify.dev/docs/apps/build/metafields/definitions) exists with owner type `Product` and type `list.metaobject_reference` (for example, `custom.color-pattern`). *** ## How 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. *** ## Step 1: Create metaobject entries Use [`metaobjectCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation MetaobjectCreate { metaobjectCreate(metaobject: { # Use the standard Shopify color-pattern definition. type: "custom--color-pattern", fields: [ { key: "color_taxonomy_reference", # Reference Shopify's taxonomy values for colors (IDs 3 and 10). # These connect your product to the global taxonomy. value: "[\"gid://shopify/TaxonomyValue/3\", \"gid://shopify/TaxonomyValue/10\"]" }, { key: "pattern_taxonomy_reference", # Reference the pattern taxonomy value (ID 2874). value: "gid://shopify/TaxonomyValue/2874" }, { key: "label", # This label is what customers will see as the option value name. value: "Orange/Blue" } ] }) { metaobject { id displayName fields { key value } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "metaobjectCreate": { "metaobject": { "id": "gid://shopify/Metaobject/70095274073", "displayName": "Orange/Blue", "fields": [ { "key": "color_taxonomy_reference", "value": "[\"gid://shopify/TaxonomyValue/3\", \"gid://shopify/TaxonomyValue/10\"]" }, { "key": "pattern_taxonomy_reference", "value": "gid://shopify/TaxonomyValue/2874" }, { "key": "label", "value": "Orange/Blue" } ] }, "userErrors": [] } } } ``` *** ## Step 2: Create the product Use [`productCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation CreateProduct { productCreate(product: { title: "T-Shirt", # Assign a taxonomy category for better marketplace integration. category: "gid://shopify/TaxonomyCategory/aa-1-13-7", # Create a basic Size option. You'll add the linked Color option in Step 3. productOptions: [ { name: "Size", values: [ { name: "Small" }, { name: "Medium" } ] } ] }) { product { id title options { id name optionValues { id name } } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "productCreate": { "product": { "id": "gid://shopify/Product/456", "title": "T-Shirt", "options": [ { "id": "gid://shopify/ProductOption/101", "name": "Size", "optionValues": [ { "id": "gid://shopify/ProductOptionValue/1", "name": "Small" }, { "id": "gid://shopify/ProductOptionValue/2", "name": "Medium" } ] } ] }, "userErrors": [] } } } ``` *** ## Step 3: Add the linked option Use [`productOptionsCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](#step-1-create-metaobject-entries). The following example adds a linked `Color` option: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation AddLinkedColorOption { productOptionsCreate( # Use the product ID from Step 2. productId: "gid://shopify/Product/456", options: [ { name: "Color", # Link to the metafield definition that references your color pattern metaobject. linkedMetafield: { namespace: "custom", key: "color-pattern" }, values: [ # Reference the metaobject ID from Step 1. { linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" } ] } ] ) { product { id title options { id name linkedMetafield { namespace key } optionValues { id name linkedMetafieldValue } } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "productOptionsCreate": { "product": { "id": "gid://shopify/Product/456", "title": "T-Shirt", "options": [ { "id": "gid://shopify/ProductOption/101", "name": "Size", "linkedMetafield": null, "optionValues": [ { "id": "gid://shopify/ProductOptionValue/1", "name": "Small", "linkedMetafieldValue": null }, { "id": "gid://shopify/ProductOptionValue/2", "name": "Medium", "linkedMetafieldValue": null } ] }, { "id": "gid://shopify/ProductOption/102", "name": "Color", "linkedMetafield": { "namespace": "custom", "key": "color-pattern" }, "optionValues": [ { "id": "gid://shopify/ProductOptionValue/3", "name": "Orange/Blue", "linkedMetafieldValue": "gid://shopify/Metaobject/70095274073" } ] } ] }, "userErrors": [] } } } ``` *** ## Step 4: Add values to an existing linked option Use [`productOptionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](#step-1-create-metaobject-entries)), then add it to the option. The new value has `hasVariants: false` until you create variants in [Step 5](#step-5-create-variants-for-linked-option-values). ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation AddLinkedOptionValue { productOptionUpdate( productId: "gid://shopify/Product/456", option: { # The Color option ID from Step 3. id: "gid://shopify/ProductOption/102" }, # Add a new value to the existing linked option. optionValuesToAdd: [ { # Reference the new metaobject (create it first using Step 1). linkedMetafieldValue: "gid://shopify/Metaobject/70095274074" } ] ) { product { options { id name linkedMetafield { namespace key } optionValues { id name linkedMetafieldValue hasVariants } } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "productOptionUpdate": { "product": { "options": [ { "id": "gid://shopify/ProductOption/101", "name": "Size", "linkedMetafield": null, "optionValues": [ { "id": "gid://shopify/ProductOptionValue/1", "name": "Small", "linkedMetafieldValue": null, "hasVariants": true }, { "id": "gid://shopify/ProductOptionValue/2", "name": "Medium", "linkedMetafieldValue": null, "hasVariants": true } ] }, { "id": "gid://shopify/ProductOption/102", "name": "Color", "linkedMetafield": { "namespace": "custom", "key": "color-pattern" }, "optionValues": [ { "id": "gid://shopify/ProductOptionValue/3", "name": "Orange/Blue", "linkedMetafieldValue": "gid://shopify/Metaobject/70095274073", "hasVariants": true }, { "id": "gid://shopify/ProductOptionValue/4", "name": "Red/White", "linkedMetafieldValue": "gid://shopify/Metaobject/70095274074", "hasVariants": false } ] } ] }, "userErrors": [] } } } ``` *** ## Step 5: Create variants for linked option values After adding a new linked option value, create variants to make it purchasable. Use [`productVariantsBulkCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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. ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation CreateVariantsForLinkedOption { productVariantsBulkCreate( productId: "gid://shopify/Product/456", variants: [ { price: 29.99, optionValues: [ # Use "name" for regular options. { optionName: "Size", name: "Small" }, # Use "linkedMetafieldValue" for linked options (metaobject ID from Step 4). { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274074" } ] }, { price: 29.99, optionValues: [ { optionName: "Size", name: "Medium" }, { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274074" } ] } ] ) { productVariants { id title price selectedOptions { name value } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "productVariantsBulkCreate": { "productVariants": [ { "id": "gid://shopify/ProductVariant/301", "title": "Small / Red/White", "price": "29.99", "selectedOptions": [ { "name": "Size", "value": "Small" }, { "name": "Color", "value": "Red/White" } ] }, { "id": "gid://shopify/ProductVariant/302", "title": "Medium / Red/White", "price": "29.99", "selectedOptions": [ { "name": "Size", "value": "Medium" }, { "name": "Color", "value": "Red/White" } ] } ], "userErrors": [] } } } ``` *** ## Next steps * Learn more about [metafields](https://shopify.dev/docs/apps/build/metafields) and [metaobjects](https://shopify.dev/docs/apps/build/metaobjects). * Learn how to [add product data](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/add-data). * Explore the [`productOptionsCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productOptionsCreate), [`productOptionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productOptionUpdate), [`productVariantsBulkCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productVariantsBulkCreate), and [`metaobjectCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectCreate) mutations in the GraphQL Admin API reference. *** * [Requirements](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#requirements) * [How it works](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#how-it-works) * [Step 1: Create metaobject entries](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-1-create-metaobject-entries) * [Step 2: Create the product](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-2-create-the-product) * [Step 3: Add the linked option](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-3-add-the-linked-option) * [Step 4: Add values to an existing linked option](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-4-add-values-to-an-existing-linked-option) * [Step 5: Create variants for linked option values](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#step-5-create-variants-for-linked-option-values) * [Next steps](https://shopify.dev/docs/apps/build/product-merchandising/products-and-collections/metafield-linked.md#next-steps)