---
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
api_name: admin
---

# 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#authenticated-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.

***