Skip to main content

Manage metafields

Metafields are a flexible way for your app to add and store additional information about a Shopify resource. If you want to include data validation for metafield values, then you can create metafield definitions.

This guide shows you how to manage metafields using the GraphQL Admin API.

Anchor to RequirementsRequirements

  • Your app can make authenticated requests to the GraphQL Admin API.

  • You've created products in your store.

    The following steps demonstrate how to create, retrieve, update, and delete metafields using the GraphQL Admin API. You'll learn how to add custom data to your products and manage that data throughout its lifecycle.

Anchor to Step 1: Create a metafieldStep 1: Create a metafield

You can create any number of metafields for a resource, and they'll be accessible to any app. To create a metafield, use a GraphQL mutation to create or update the resource that you want the metafields to belong to.

The following example adds a metafield to a product by using the productUpdate mutation:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
productUpdate(
input : {
id: "gid://shopify/Product/1",
metafields: [
{
namespace: "custom",
key: "wash-instructions",
value: "cold wash",
type: "single_line_text_field"
}
]
}) {
product {
metafields(first: 100) {
edges {
node {
namespace
key
value
}
}
}
}
}
}

JSON response

{
"data": {
"productUpdate": {
"product": {
"metafields": {
"edges": [
{
"node": {
"namespace": "custom",
"key": "wash-instructions",
"value": "cold wash"
}
}
]
}
}
}
}
}

Anchor to Step 2: Retrieve a metafieldStep 2: Retrieve a metafield

When you query a resource, you can retrieve its metafields. Use the metafield field to return a single metafield. Specify the metafield that you want to retrieve by using the namespace and key arguments.

The following example queries a product for the value of the associated custom.wash-instructions metafield:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query {
product(id: "gid://shopify/Product/1") {
metafield(namespace: "custom", key: "wash-instructions") {
value
}
}
}

JSON response

{
"data": {
"product": {
"metafield": {
"value": "cold wash"
}
}
}
}

Anchor to Step 3: Update a metafieldStep 3: Update a metafield

To update a metafield, use a GraphQL mutation to update the owning resource, and include the metafield in the mutation input. Specify the owning resource and the metafields that you're updating by their IDs.

The following example updates a metafield that belongs to a product by using the productUpdate mutation:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
productUpdate(
input : {
id: "gid://shopify/Product/1",
metafields: [
{
namespace: "custom",
key: "wash-instructions",
value: "hang dry"
}
]
}) {
product {
metafields(first: 10) {
edges {
node {
namespace
key
value
}
}
}
}
}
}

JSON response

{
"data": {
"productUpdate": {
"product": {
"metafields": {
"edges": [
{
"node": {
"key": "wash-instructions",
"value": "cold wash"
}
},
{
"node": {
"key": "dry",
"value": "hang dry"
}
}
]
}
}
}
}
}

Anchor to Step 4 (Optional): Delete a metafieldStep 4 (Optional): Delete a metafield

To delete a metafield, use the metafieldsDelete mutation. In the input, specify the ID of the metafield to delete.

The following example deletes a metafield by ID:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation DeleteMetafieldByNamespaceAndKey {
metafieldsDelete(
metafields: [
{
ownerId: "gid://shopify/Product/1",
namespace: "custom",
key: "wash-instructions"
}
]
) {
deletedMetafields {
key
namespace
ownerId
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"metafieldsDelete": {
"deletedMetafields": [
{
"key": "wash-instructions",
"namespace": "custom",
"ownerId": "gid://shopify/Product/1"
}
],
"userErrors": []
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?