How to set `optionValues` for a product variant that is linked to a metafield value?

GraphQL Admin API Troubleshooting
1

Hi,

We are trying to set the optionValues, for a product variant where the optionValues that are linked to a metafieldValue, using the productVariantsBulkCreate and/of productVariantsBulkUpdate mutations, and we run into a confusing set of error messages.


Let’s try to update the optionValues with a productVariantsBulkUpdate mutation (for full mutation, see below), for a product option that is linked to a metafield value:

"optionValues": [
  {
    "optionName": "Color",
    "name": "Red",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: Cannot set name for an option value linked to a metafield

Ok, let’s remove the name:

"optionValues": [
  {
    "optionName": "Color",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: id or name must be specified

Ok… let’s try adding an id instead of a name then?

"optionValues": [
  {
    "optionName": "Color",
    "id": "gid://shopify/ProductOptionValue/3540024983765",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: Cannot set id for an option value linked to a metafield

Maybe I need to only provide a linkedMetafieldValue?

"optionValues": [
  {
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: optionId or optionName must be specified

As you can see, the error message seem to point in a circle. Which kind-off suggests that setting a linkedMetafieldValue through the GraphQL API (version: 2025-04) is not supported?!


Our question

How do we set the optionValue for product options, that are linked to a metafield vale, using the productVariantsBulkCreate and/of productVariantsBulkUpdate mutations?

Thanks in advance!


For reference: full GraphQL mutation used: 
// Mutation
mutation ($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

// Variables
{
  "productId": "gid://shopify/Product/8902245974229",
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/51310185382101",
      "optionValues": (... see above ...)
    }
  ]
}

For reference: the following block will update the `optionValues` for a product option that is **not** linked to a metafield value, without error: 
"optionValues": [
  {
    "optionName": "Style",
    "name": "Fancy",
  }
]

# Ok (no errors)
1 Like
2

Hey @Jacco :waving_hand: just out of curiosity, are you trying to change any part of the option values for those particular variants or swap variant IDs between products?

For example, if you’re trying to rename a product option but keep the metaobjects the same, we’ll return this error. There’s a bit more info in this thread here, but in cases where you need to adjust product options directly, we recommend using something like productOptionUpdate (you can update multiple options with this mutation, including removing, adding, etc.).

Just wondering what your use case is here/if that’s what you’re doing - happy to help out further :slight_smile:

3

Hey @Alan_G,

I had read the thread you linked, but it does not solve our issue.

This is part of an App that synchronizes (configurable fields) products between 2 or more stores owned by the same merchant. So when the merchant makes a change to a product on one of those stores, the change is pushed to the other stores.

This particular case comes up when the merchant decides to add a product option that is connected to a metafield (for example ‘color’), or adds a product option value to an existing product options, that is connected to a metafield.

In both cases, we run into the same issue and error messages.

We do use the productOptionUpdate and/or productOptionCreate mutations, before pushing the productVariantsBulkCreate and/or productVariantsBulkUpdate mutations, to make sure the product options are available, at the store the change is being pushed to (because otherwise, we run into other errors), and got the metaobject IDs relevant to the store that is being pushed to.


Also please note that our App’s logic works without errors when creating, updating and/or deleting product options, product option values, and variants, as long as the product option is not linked to a metafield.


For reference: I also came across a question over at the community.shopify.com forums, that ran into the same issue: productVariantsBulkCreate: Cannot Set options for Linked Metafield - Shopify Community

5

Hi @Alan_G,

Let me rephrase my question.

Let’s say I have this product, with a single product option (Shape), that is not linked to a metafield:

The product as shown in the dashboard, with one product option
The product as shown in the dashboard, with one product option635×1157 85.1 KB

{
  "product": {
    "id": "gid://shopify/Product/8240700719262",
    "title": "Widget",
    "options": [
      {
        "id": "gid://shopify/ProductOption/10510620131486",
        "name": "Shape",
        "position": 1,
        "linkedMetafield": null,
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139788730526",
            "name": "Square",
            "linkedMetafieldValue": null
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139788763294",
            "name": "Round",
            "linkedMetafieldValue": null
          }
        ]
      }
    ],
    "variants": {
      "nodes": [
        {
          "id": "gid://shopify/ProductVariant/45314272002206",
          "title": "Square",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314272034974",
          "title": "Round",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            }
          ]
        }
      ]
    }
  }
}

What GraphQL mutations do I need to do, to add a product option (Color, in this example), that is linked to a metafield:

The product as shown in the dashboard, with two product options
The product as shown in the dashboard, with two product options635×1247 93.2 KB

{
  "product": {
    "id": "gid://shopify/Product/8240700719262",
    "title": "Widget",
    "options": [
      {
        "id": "gid://shopify/ProductOption/10510620131486",
        "name": "Shape",
        "position": 1,
        "linkedMetafield": null,
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139788730526",
            "name": "Square",
            "linkedMetafieldValue": null
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139788763294",
            "name": "Round",
            "linkedMetafieldValue": null
          }
        ]
      },
      {
        "id": "gid://shopify/ProductOption/10510624325790",
        "name": "Color",
        "position": 2,
        "linkedMetafield": {
          "namespace": "shopify",
          "key": "color-pattern"
        },
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139812126878",
            "name": "Blue",
            "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139812159646",
            "name": "Green",
            "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
          }
        ]
      }
    ],
    "variants": {
      "nodes": [
        {
          "id": "gid://shopify/ProductVariant/45314272002206",
          "title": "Square / Blue",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812126878",
                "name": "Blue",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314293530782",
          "title": "Square / Green",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812159646",
                "name": "Green",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314272034974",
          "title": "Round / Blue",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812126878",
                "name": "Blue",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314293563550",
          "title": "Round / Green",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812159646",
                "name": "Green",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
              }
            }
          ]
        }
      ]
    }
  }
}

If we know which GraphQL mutations are needed to make this happen, we can most likely figure out the rest on our own :slight_smile:


For reference: the query used to fetch the GraphQL data:

# query
query ($id: ID!) {
  product(id: $id) {
    id
    title
    options {
      id
      name
      position
      linkedMetafield {
        namespace
        key
      }
      optionValues {
        id
        name
        linkedMetafieldValue
      }
    }
    variants(first: 10) {
      nodes {
        id
        title
        selectedOptions {
          name
          optionValue {
            id
            name
            linkedMetafieldValue
          }
        }
      }
    }
  }
}

# variables
{
  "id": "gid://shopify/Product/8240700719262"
}
6

Hey @Jacco - thanks for clarifying. Generally, you should be able to use the metaobjectCreate and then our recommendation is to use the productSet mutation to link the metafield-linked option to a product. There’s a bit more info in our documentation here: Metafield-linked product options but, the general method would be something like this:

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

variables:

{
  "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"
      }
    ]
  }
}

The Taxonomy Values referenced there can be found here if needed, but you should be able to use any custom metafield as the value. Once the option is linked to a metafield though, you should be able to link option values to the right metaobject entry in the bulk update mutation too.

Hope this helps/makes sense - let me know if I can clarify anything as always here!

7

When you write “(…) and then our recommendation is to use the productSet mutation to link the metafield-linked option to a product.”

Does that mean that the productVariantsBulkCreate and productVariantsBulkUpdate mutations are not supported, when it comes to creating/updating existing products for this use case?

While it is probably possible to build an expensive workaround, we originally decided against using the productSet mutation, because it lacks the granularity we need.