Anchor to section titled 'undefined'

metafieldsSet
mutation

Requires the same access level needed to mutate the owner resource. For instance, if you want to set a metafield on a product, you need the same permissions as you would need to mutate a product.

Sets metafield values. Metafield values will be set regardless if they were previously created or not.

Allows a maximum of 25 metafields to be set at a time.

This operation is atomic, meaning no changes are persisted if an error is encountered.

As of 2024-07, this operation supports compare-and-set functionality to better handle concurrent requests. If compareDigest is set for any metafield, the mutation will only set that metafield if the persisted metafield value matches the digest used on compareDigest. If the metafield doesn't exist yet, but you want to guarantee that the operation will run in a safe manner, set compareDigest to null. The compareDigest value can be acquired by querying the metafield object and selecting compareDigest as a field. If the compareDigest value does not match the digest for the persisted value, the mutation will return an error. You can opt out of write guarantees by not sending compareDigest in the request.

Anchor to section titled 'Arguments'

Arguments

Anchor to metafields
metafields
[MetafieldsSetInput!]!
required

The list of metafield values to set. Maximum of 25.

Was this section helpful?
Anchor to section titled 'MetafieldsSetPayload returns'

MetafieldsSetPayload returns

Anchor to MetafieldsSetPayload.metafields
metafields
[Metafield!]

The list of metafields that were set.

Anchor to MetafieldsSetPayload.userErrors
userErrors
[MetafieldsSetUserError!]!
non-null

The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Hide code
DescriptionCopy
mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      key
      namespace
      value
      createdAt
      updatedAt
    }
    userErrors {
      field
      message
      code
    }
  }
}
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { metafields { key namespace value createdAt updatedAt } userErrors { field message code } } }",
 "variables": {
    "metafields": [
      {
        "key": "materials",
        "namespace": "my_fields",
        "ownerId": "gid://shopify/Product/20995642",
        "type": "multi_line_text_field",
        "value": "95% Cotton\n5% Spandex"
      },
      {
        "key": "manufactured",
        "namespace": "my_fields",
        "ownerId": "gid://shopify/Product/20995642",
        "type": "single_line_text_field",
        "value": "Made in Canada"
      }
    ]
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields {
        key
        namespace
        value
        createdAt
        updatedAt
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
      "metafields": [
        {
          "key": "materials",
          "namespace": "my_fields",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "multi_line_text_field",
          "value": "95% Cotton\n5% Spandex"
        },
        {
          "key": "manufactured",
          "namespace": "my_fields",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "single_line_text_field",
          "value": "Made in Canada"
        }
      ]
    },
  },
);

const data = await response.json();

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields {
        key
        namespace
        value
        createdAt
        updatedAt
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "metafields": [{"key"=>"materials", "namespace"=>"my_fields", "ownerId"=>"gid://shopify/Product/20995642", "type"=>"multi_line_text_field", "value"=>"95% Cotton\n5% Spandex"}, {"key"=>"manufactured", "namespace"=>"my_fields", "ownerId"=>"gid://shopify/Product/20995642", "type"=>"single_line_text_field", "value"=>"Made in Canada"}]
}

response = client.query(query: query, variables: variables)

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
      metafieldsSet(metafields: $metafields) {
        metafields {
          key
          namespace
          value
          createdAt
          updatedAt
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
      "metafields": [
        {
          "key": "materials",
          "namespace": "my_fields",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "multi_line_text_field",
          "value": "95% Cotton\n5% Spandex"
        },
        {
          "key": "manufactured",
          "namespace": "my_fields",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "single_line_text_field",
          "value": "Made in Canada"
        }
      ]
    },
  },
});

use Shopify\Clients\Graphql;

$client = new Graphql("your-development-store.myshopify.com", $accessToken);
$query = <<<QUERY
  mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields {
        key
        namespace
        value
        createdAt
        updatedAt
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY;

$variables = [
  "metafields" => [{"key"=>"materials", "namespace"=>"my_fields", "ownerId"=>"gid://shopify/Product/20995642", "type"=>"multi_line_text_field", "value"=>"95% Cotton\n5% Spandex"}, {"key"=>"manufactured", "namespace"=>"my_fields", "ownerId"=>"gid://shopify/Product/20995642", "type"=>"single_line_text_field", "value"=>"Made in Canada"}],
];

$response = $client->query(["query" => $query, "variables" => $variables]);
Hide code
Input variables
Copy
{
  "metafields": [
    {
      "key": "materials",
      "namespace": "my_fields",
      "ownerId": "gid://shopify/Product/20995642",
      "type": "multi_line_text_field",
      "value": "95% Cotton\n5% Spandex"
    },
    {
      "key": "manufactured",
      "namespace": "my_fields",
      "ownerId": "gid://shopify/Product/20995642",
      "type": "single_line_text_field",
      "value": "Made in Canada"
    }
  ]
}
Hide code
Response
JSON
{
  "metafieldsSet": {
    "metafields": [
      {
        "key": "materials",
        "namespace": "my_fields",
        "value": "95% Cotton\n5% Spandex",
        "createdAt": "2024-09-12T01:50:08Z",
        "updatedAt": "2024-09-12T01:50:19Z"
      },
      {
        "key": "manufactured",
        "namespace": "my_fields",
        "value": "Made in Canada",
        "createdAt": "2024-09-12T01:50:19Z",
        "updatedAt": "2024-09-12T01:50:19Z"
      }
    ],
    "userErrors": []
  }
}