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.

Arguments

Anchor to metafieldsmetafields • [MetafieldsSetInput!]!required: The list of metafield values to set. Maximum of 25.

Was this section helpful?

Anchor to MetafieldsSetPayload returnsMetafieldsSetPayload returns

Anchor to metafieldsmetafields • [Metafield!]: The list of metafields that were set.
Anchor to userErrorsuserErrors • [MetafieldsSetUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

1const { admin } = await authenticate.admin(request);
2
3const response = await admin.graphql(
4  `#graphql
5  mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
6    metafieldsSet(metafields: $metafields) {
7      metafields {
8        key
9        namespace
10        value
11        createdAt
12        updatedAt
13      }
14      userErrors {
15        field
16        message
17        code
18      }
19    }
20  }`,
21  {
22    variables: {
23      "metafields": [
24        {
25          "key": "example_key",
26          "namespace": "example_namespace",
27          "ownerId": "gid://shopify/Product/20995642",
28          "type": "single_line_text_field",
29          "value": "Example Value"
30        }
31      ]
32    },
33  },
34);
35
36const data = await response.json();
37

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": "example_key",
        "namespace": "example_namespace",
        "ownerId": "gid://shopify/Product/20995642",
        "type": "single_line_text_field",
        "value": "Example Value"
      }
    ]
  }
}'

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": "example_key",
          "namespace": "example_namespace",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "single_line_text_field",
          "value": "Example Value"
        }
      ]
    },
  },
);

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"=>"example_key", "namespace"=>"example_namespace", "ownerId"=>"gid://shopify/Product/20995642", "type"=>"single_line_text_field", "value"=>"Example Value"}]
}

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": "example_key",
          "namespace": "example_namespace",
          "ownerId": "gid://shopify/Product/20995642",
          "type": "single_line_text_field",
          "value": "Example Value"
        }
      ]
    },
  },
});

Input variables

JSON

1{
2  "metafields": [
3    {
4      "key": "example_key",
5      "namespace": "example_namespace",
6      "ownerId": "gid://shopify/Product/20995642",
7      "type": "single_line_text_field",
8      "value": "Example Value"
9    }
10  ]
11}

Response

JSON

1{
2  "metafieldsSet": {
3    "metafields": [
4      {
5        "key": "example_key",
6        "namespace": "example_namespace",
7        "value": "Example Value",
8        "createdAt": "2024-11-18T21:40:28Z",
9        "updatedAt": "2024-11-18T21:40:28Z"
10      }
11    ],
12    "userErrors": []
13  }
14}