productVariantsBulkCreate: Cannot Set options for Linked Metafield

[konsole]

Hi there 👋,

I’m trying to bulk create product variants using Shopify's GraphQL API. However, I’m running into a series of conflicting and confusing error messages when trying to configure optionValues, particularly when working with a linkedMetafieldValue. (shopify.color-pattern field for eg).

tldr;

• Encountered an error stating: "optionId or optionName must be specified." during first attempt
• After adding optionName, received a new error: "id or name must be specified."
• Included name, but the response then stated: "Cannot set name for an option value linked to a metafield."
• Seeking clarification on the correct configuration for optionValues when utilizing a linkedMetafieldValue.

Further details

First Attempt

curl -X POST https://<store>.myshopify.com/admin/api/2025-01/graphql.json \
-H "Content-Type: application/json" \
-H "X-Shopify-Access-Token: <redacted>" \
-d '{
    "query": "
    mutation ProductVariantsCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
      productVariantsBulkCreate(productId: $productId, variants: $variants) {
        product {
          id
        }
        userErrors {
          field
          message
          code
        }
      }
    }",
    "variables":
    {
        "productId": "gid://shopify/Product/8737843085536",
        "variants":
        [
            {
                "barcode": "",
                "inventoryItem":
                {
                    "cost": 0,
                    "countryHarmonizedSystemCodes": null,
                    "measurement":
                    {
                        "weight":
                        {
                            "unit": "OUNCES",
                            "value": 2
                        }
                    },
                    "requiresShipping": true,
                    "tracked": true
                },
                "inventoryPolicy": "DENY",
                "optionValues":
                [
                    {
                        "name": "Selling Plans Ski Wax",
                        "optionName": "Title"
                    },
                    {
                        "linkedMetafieldValue": "gid://shopify/Metaobject/103203111136"
                    }
                ],
                "price": "24.95",
                "requiresComponents": false,
                "taxCode": "",
                "taxable": true
            }
        ]
    }
}'

Response

{
    "data":
    {
        "productVariantsBulkCreate":
        {
            "product": null,
            "userErrors":
            [
                {
                    "field":
                    [
                        "variants",
                        "0",
                        "optionValues",
                        "1"
                    ],
                    "message": "optionId or optionName must be specified",
                    "code": "INVALID_INPUT"
                }
            ]
        }
    }
}

Second Attempt

Alright, fine! I'll add the optionID or optionName as suggested in the error message. I added the optionName

curl -X POST https://<store>.myshopify.com/admin/api/2025-01/graphql.json \
-H "Content-Type: application/json" \
-H "X-Shopify-Access-Token: <redacted>" \
-d '{
    "query": "
    mutation ProductVariantsCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
      productVariantsBulkCreate(productId: $productId, variants: $variants) {
        product {
          id
        }
        userErrors {
          field
          message
          code
        }
      }
    }",
    "variables":
    {
        "productId": "gid://shopify/Product/8737843085536",
        "variants":
        [
            {
                "barcode": "",
                "inventoryItem":
                {
                    "cost": 0,
                    "countryHarmonizedSystemCodes": null,
                    "measurement":
                    {
                        "weight":
                        {
                            "unit": "OUNCES",
                            "value": 2
                        }
                    },
                    "requiresShipping": true,
                    "tracked": true
                },
                "inventoryPolicy": "DENY",
                "optionValues":
                [
                    {
                        "name": "Selling Plans Ski Wax",
                        "optionName": "Title"
                    },
                    {
                        "linkedMetafieldValue": "gid://shopify/Metaobject/103203111136",
                        "optionName": "Color"
                    }
                ],
                "price": "24.95",
                "requiresComponents": false,
                "taxCode": "",
                "taxable": true
            }
        ]
    }
}'

Response

{
    "data":
    {
        "productVariantsBulkCreate":
        {
            "product": null,
            "userErrors":
            [
                {
                    "field":
                    [
                        "variants",
                        "0",
                        "optionValues",
                        "1"
                    ],
                    "message": "id or name must be specified",
                    "code": "INVALID_INPUT"
                }
            ]
        }
    }
}

Third Attempt

OK, I'll add value id or name.

curl -X POST https://<store>.myshopify.com/admin/api/2025-01/graphql.json \
-H "Content-Type: application/json" \
-H "X-Shopify-Access-Token: <redacted>" \
-d '{
    "query": "
    mutation ProductVariantsCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
      productVariantsBulkCreate(productId: $productId, variants: $variants) {
        product {
          id
        }
        userErrors {
          field
          message
          code
        }
      }
    }",
    "variables":
    {
        "productId": "gid://shopify/Product/8737843085536",
        "variants":
        [
            {
                "barcode": "",
                "inventoryItem":
                {
                    "cost": 0,
                    "countryHarmonizedSystemCodes": null,
                    "measurement":
                    {
                        "weight":
                        {
                            "unit": "OUNCES",
                            "value": 2
                        }
                    },
                    "requiresShipping": true,
                    "tracked": true
                },
                "inventoryPolicy": "DENY",
                "optionValues":
                [
                    {
                        "name": "Selling Plans Ski Wax",
                        "optionName": "Title"
                    },
                    {
                        "linkedMetafieldValue": "gid://shopify/Metaobject/103203111136",
                        "optionName": "Color",
                        "name": "Red"
                    }
                ],
                "price": "24.95",
                "requiresComponents": false,
                "taxCode": "",
                "taxable": true
            }
        ]
    }
}'

Response

{
    "data":
    {
        "productVariantsBulkCreate":
        {
            "product": null,
            "userErrors":
            [
                {
                    "field":
                    [
                        "variants",
                        "0",
                        "optionValues",
                        "1"
                    ],
                    "message": "Cannot set name for an option value linked to a metafield",
                    "code": "CANNOT_SET_NAME_FOR_LINKED_OPTION_VALUE"
                }
            ]
        }
    }
}

To summarize:

1. The first error suggested that I need to specify optionId or optionName.
2. The second error said I need to specify id or name.
3. The third error said I can't set name for an option value linked to a metafield.

The error messages seem to contradict themselves. Am I missing anything obvious here? What would be the proper request payload for adding options with linkedMetafieldValue?

Thanks in advance!

[Jacco-V]

I've run into the exact same issue, with the exact same set of error messages 😞

Did you find a solution to this problem by any chance?

[Jacco-V]

To extends my question:

For a `productVariantsBulkUpdate` mutation, the following block should set the `optionValues`:

"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

Which basically seems to boil down to: setting a `linkedMetafieldValue` through the GraphQL API (version: 2025-04) is not supported?!

[ZephyrSoft]

No estoy seguro, pero mi respuesta en este otro post tal vez pueda ayudar un poco.

https://community.shopify.com/c/shopify-flow-app/link-option-to-metafield/m-p/3053555/highlight/true...

Podría probar con algo asi:

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

 Evitando usar name ya que será tomado del metaobject referenciado.

[Jacco-V]

Your solution is for updating `productOptions` with the `productOptionUpdate` mutation. This topic is about updating the `optionValues` for a product variant with the `productVariantsBulkUpdate` mutation.