Creating products & variants with linkedMetafield

[Ronald_G]

We are using GraphQL 2025-07, has anyone had success following this Shopify article on Metafield-linked product options to create products with variants that has linkedMetafieldValues?

We’ve tried the following:

1. metaobjectCreate + productSet per the help article - we get error “Option ‘Color’ must specify at least one option value.” See code blocks below. (We also had to fix the error that Shopify variant positions now start with 1 instead of 0)
2. productCreate + productVariantsBulkCreate - we verified that the linkedMetafieldValues exist on product options, but productVariantsBulkCreate raises id or name must be specified
3. productCreate + productOptionUpdate + productVariantsBulkCreate - we get id or name must be specified

Here are the steps for #1

1. Verify metaobject exists:

query ($id: ID!) {
  metaobject(id: $id) {
    id
    type
    displayName
    handle
    fields {
      key
      value
    }
  }
}

Results:

{“id”=>“gid://shopify/Metaobject/52316602535”, “type”=>“shopify–color-pattern”, “displayName”=>“Gold”, “handle”=>“gold”, “fields”=>[{“key”=>“label”, “value”=>“Gold”}, {“key”=>“color”, “value”=>“#D49A06”}, {“key”=>“image”, “value”=>nil}, {“key”=>“color_taxonomy_reference”, “value”=>“["gid://shopify/TaxonomyValue/4"]”}, {“key”=>“pattern_taxonomy_reference”, “value”=>“gid://shopify/TaxonomyValue/2874”}]}

{"id"=>"gid://shopify/Metaobject/52316569767", "type"=>"shopify--color-pattern", "displayName"=>"Bronze", "handle"=>"bronze", "fields"=>[{"key"=>"label", "value"=>"Bronze"}, {"key"=>"color", "value"=>"#CD7F32"}, {"key"=>"image", "value"=>nil}, {"key"=>"color_taxonomy_reference", "value"=>"[\"gid://shopify/TaxonomyValue/657\"]"}, {"key"=>"pattern_taxonomy_reference", "value"=>"gid://shopify/TaxonomyValue/2874"}]}

2. productSet with parameters

{
  title: "product name set",
  vendor: "Product Test",
  status: "ACTIVE",
  productType: "Bracelet",
  productOptions: [
    {
      name: "Color",
      linkedMetafield: {
        namespace: "shopify",
        key: "color-pattern"
      }
    }
  ],
  variants: [
    {
      optionValues: [{ optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/52316602535"}],
      sku: "PT-322353-1",
    },
    {
      optionValues: [{ optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/52316569767"}],
      sku: "PT-322353-2",
    }
  ]
}

Error raised:
‘Color’ must specify at least one option value.

[Alan_G]

Hey @Ronald_G - when creating the the product, are you setting the product category as well? Here’s a quick example per the docs there:

mutation productSet {
  productSet(synchronous: true, input: {
    title: "T-Shirt"
    category: "gid://shopify/TaxonomyCategory/aa-1-13-7"
    productOptions: [
      {
        name: "Size",
        values: [
          { name: "Small"},
          { name: "Medium"},
        ]
      },
      {
        name: "Color",
        linkedMetafield: {
          namespace: "shopify",
          key: "color-pattern",
        }
      }
    ],
    variants: [
      {
        position: 0
        optionValues: [
          { optionName: "Size", name: "Small" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" }
        ]
      },
      {
        position: 1
        optionValues: [
          { optionName: "Size", name: "Medium" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" }
        ]
      }
    ]
  }) {
    userErrors { message }
    product {
      id
    }
  }
}

You should be able to grab a product category ID here: 2025-03

Could you let me know if added the category to the productSet mutation resolves things or if the issue persists? Happy to help out further if need be for sure!

[Ronald_G]

Thanks @Alan_G

We tried the sample code and it didn’t work.

We also assumed the metaobject ID is store specific? If so, we created a new product via Shopify admin (“gid://shopify/Product/8579978887335”), found the category ID and metaobject IDs, and tried to use productSet in GraphiQL, but still got “Option ‘Color’ must specify at least one option value.” See screenshots below:

mutation productSet {
  productSet(synchronous: true, input: {
    title: "T-Shirt"
    category: "gid://shopify/TaxonomyCategory/aa-1-13-8"
    productOptions: [
      {
        name: "Size",
        values: [
          { name: "Small"},
          { name: "Medium"},
        ]
      },
      {
        name: "Color",
        linkedMetafield: {
          namespace: "shopify",
          key: "color-pattern",
        }
      }
    ],
    variants: [
      {
        position: 1
        optionValues: [
          { optionName: "Size", name: "Small" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/122144719015" }
        ]
      },
      {
        position: 2
        optionValues: [
          { optionName: "Size", name: "Medium" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/122144751783" }
        ]
      }
    ]
  }) {
    userErrors { message }
    product {
      id
    }
  }
}		  

[Alan_G]

Hey @Ronald_G - thanks for trying that. Are you setting up the metaobjects as well? In the guide there we have an example that might help. Just posting here for ease of reference:

mutation MetaobjectCreate($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    metaobject {
      id
      displayName
      fields {
        key
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "metaobject": {
    "type": "shopify--color-pattern",
    "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"
      }
    ]
  }
}

If you’re using pre-existing metafields without the set taxonomy values that might be why that error is popping up. Let me know if you’re still seeing the issue pop up and I’m happy to keep troubleshooting with you.

[Ronald_G]

Hi @Alan_G

I have a couple general questions:

• Can metaobjects be reused for multiple products? Or does each product option needs it’s own metaobject?
• Is there a help article on TaxonomyValue on what the valid values are? This Shopify.dev article isn’t helpful

I created 2 new metaobjects (“gid://shopify/Metaobject/153379340588” and “gid://shopify/Metaobject/153379602732”) and tried to use productSet, but still same error: “Option ‘Color’ must specify at least one option value.” See code and screenshots below.

Created “gid://shopify/Metaobject/153379340588” as Orange/Blue

Created “gid://shopify/Metaobject/153379602732” as Orange

Still same error when using productSet

mutation productSet {
  productSet(
    synchronous: true
    input: {title: "T-Shirt", category: "gid://shopify/TaxonomyCategory/aa-1-13-7", productOptions: [{name: "Size", values: [{name: "Small"}, {name: "Medium"}]}, {name: "Color", linkedMetafield: {namespace: "shopify", key: "color-pattern"}}], variants: [{position: 1, optionValues: [{optionName: "Size", name: "Small"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379340588"}]}, {position: 2, optionValues: [{optionName: "Size", name: "Medium"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379602732"}]}]}
  ) {
    userErrors {
      message
    }
    product {
      id
    }
  }
}

[Alan_G]

Hey @Ronald_G - thanks for following up here.

shopify--color-pattern metaobjects should be reusable once they’re created.

You can reference the same metaobject across multiple products and variants there, there’s no rule that a metaobject once created should be tied tro only one product.

For the “Option ‘Color’ must specify at least one option value.” error we’re seeing there, just wanted to clarify that productSet validates options before it processes variants, so this is likely why we’re seeing that pop up.

I did a little digging, and I think the example below should resolve the error:

mutation productSet {
  productSet(
    synchronous: true
    input: {title: "T-Shirt", category: "gid://shopify/TaxonomyCategory/aa-1-13-7", productOptions: [{name: "Size", values: [{name: "Small"}, {name: "Medium"}]}, {name: "Color", linkedMetafield: {namespace: "shopify", key: "color-pattern", values: ["gid://shopify/Metaobject/153379340588", "gid://shopify/Metaobject/153379602732"]}}], variants: [{position: 1, optionValues: [{optionName: "Size", name: "Small"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379340588"}]}, {position: 2, optionValues: [{optionName: "Size", name: "Medium"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379602732"}]}]}
  ) {
    userErrors {
      field
      message
    }
    product {
      id
    }
  }
}

If you add the option-level Color values and still see an error, no worries. Feel free to reach back out here and share the exact productSet input and the responses for those two metaobjects (you can redact any shop-specific details), and I’ll keep digging with you. More than happy to help as always

[Ronald_G]

Thank you @Alan_G for your help!

It looks like it worked for productSet. It looks like the Shopify.dev article is out of date.

Also, it seems that productCreate + productVariantsBulkCreate is raising id or name must be specified error. See below.

mutation productCreate($product: ProductCreateInput) {
  productCreate(product: $product) {
    product {
      id
      title
      status
      variantsCount {
        count
      }
      options {
        id
        name
        position
        values
        linkedMetafield {
          namespace
          key
        }
        optionValues {
          id
          name
          hasVariants
          linkedMetafieldValue
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "product": {
    "title": "Multiple variants + linkedMetaField",
    "category": "gid://shopify/TaxonomyCategory/aa-1-13-7",
    "productOptions": [
      {
        "name": "Color",
        "linkedMetafield": {
          "namespace": "shopify",
          "key": "color-pattern",
          "values": [
            "gid://shopify/Metaobject/122144719015",
            "gid://shopify/Metaobject/122144751783",
            "gid://shopify/Metaobject/122144784551"
          ]
        }
      }
    ]
  }
}

but productVariantsBulkCreate raises id or name must be specified error

mutation productVariantsBulkCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!, $strategy: ProductVariantsBulkCreateStrategy, $media: [CreateMediaInput!]) {
  productVariantsBulkCreate(
    productId: $productId
    media: $media
    variants: $variants
    strategy: $strategy
  ) {
    product {
      id
      title
      status
      variantsCount {
        count
      }
      options {
        id
        name
        position
        values
        linkedMetafield {
          namespace
          key
        }
        optionValues {
          id
          name
          hasVariants
          linkedMetafieldValue
        }
      }
    }
    productVariants {
      id
      displayName
      title
      sku
      position
      defaultCursor
      selectedOptions {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "productId": "gid://shopify/Product/8582130106535",
  "variants": [
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144719015"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-RED"
      }
    },
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144751783"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-YELLOW"
      }
    },
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144784551"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-GREEN"
      }
    }
  ]
}

We also tried changing optionValues to this, but then we get Cannot set name for an option value linked to a metafield

{
                  optionName: "Color",
                  name: "Green",
                  linkedMetafieldValue: "gid://shopify/Metaobject/122144784551"
                }