Retrieve metafields with the Storefront API

With the Storefront API, you can retrieve metafields but not create or update them. If you want to create, update, or delete metafields, then you need to use the GraphQL Admin API or the REST Admin API.

Storing data in metafields

Metafields are essentially additional fields for Shopify resources. There are four main parts to a metafield:

For example, a clothing shop might use metafields to store the care instructions for its clothing products. The shop could create separate metafields for washing and drying instructions, and group them by using the namespace instructions. The following example shows a metafield for washing instructions:

{
  "date": {
    "productByHandle": {
      "metafield": {
        "namespace": "instructions",
        "key": "wash",
        "value": "cold wash",
        "valueType": "STRING"
      }
    }
  }
}

The Metafield type also includes other fields, such as description and ownerType. To learn more, see the Metafield reference.

Expose metafields to the Storefront API

By default, the Storefront API can't read metafields. To expose specific metafields to the Storefront API, you need to use the GraphQL Admin API to whitelist them. For each metafield that you want to whitelist, you need to create a MetafieldStorefrontVisibility record.

Each MetafieldStorefrontVisibility record whitelists all metafields that belong to the specified resource and have a specified namespace and key combination.

To create a MetafieldStorefrontVisibility record, you can use the metafieldStorefrontVisibilityCreate mutation. The input object for the mutation uses the following fields:

• namespace — The namespace of the metafields to be visible to the Storefront API.
• key — The key of the metafields to be visible to the Storefront API.
• ownerType — The core resource that owns this metafield. For example, PRODUCT.

The following example creates a MetafieldStorefrontVisibility record that whitelists all product metafields that have the namespace instructions and the key wash.

mutation($input: MetafieldStorefrontVisibilityInput!) {
  metafieldStorefrontVisibilityCreate(
    input: $input
  ) {
    metafieldStorefrontVisibility {
      id
    }
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "namespace": "instructions",
    "key": "wash",
    "ownerType": "PRODUCT"
  }
}

{
  "data": {
    "metafieldStorefrontVisibilityCreate": {
      "metafieldStorefrontVisibility": {
        "id": "gid://shopify/MetafieldStorefrontVisibility/196664"
      },
      "userErrors": []
    }
  }
}

Any product metafield with the namespace instructions and the key wash will now be visible to the Storefront API.

Retrieve metafields with the Storefront API

After whitelisting metafields, you can retrieve them with the Storefront API by using the metafields connection or the metafield field.

Retrieve a list of metafields

The following example uses the metafields connection to retrieve a product's first five metafields. The query includes the optional namespace argument to narrow the results to metafields that have the namespace instructions.

query {
  productByHandle(handle: "the-t-shirt") {
    metafields(first: 5, namespace: "instructions") {
        edges {
        node {
          key
          value
        }
      }
    }
  }
}

{
  "data": {
    "productByHandle": {
      "metafields": {
        "edges": [
          {
            "node": {
              "key": "wash",
              "value": "cold wash"
            }
          },
          {
            "node": {
              "key": "dry",
              "value": "tumble dry"
            }
          }
        ]
      }
    }
  }
}

Retrieve a single metafield

Using the metafield field, you can retrieve a single metafield for a product or a product variant. To specify the metafield that you want to retrieve, use the namespace and key arguments.

The following example retrieves the value of a product's metafield with the namespace instructions and the key wash.

query {
  productByHandle(handle: "the-t-shirt") {
    metafield(namespace: "instructions", key: "wash") {
      value
    }
  }
}

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

Hide metafields from the Storefront API

After exposing a metafield to the Storefront API, you can hide it again by using the GraphQL Admin API to delete the MetafieldStorefrontVisibility record that you created. To delete a MetafieldStorefrontVisibility record, you need to provide its ID to the metafieldStorefrontVisibilityDelete mutation.

The following example retrieves a list of MetafieldStorefrontVisibility records. Each result returns the object's ID, namespace, key, and owner type.

query {
  metafieldStorefrontVisibilities(first:5, namespace: "instructions") {
    edges {
      node {
        id
        namespace
        key
        ownerType
      }
    }
  }
}

{
  "data": {
    "metafieldStorefrontVisibilities": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/393272",
            "namespace": "instructions",
            "key": "wash",
            "owenerType": "Product"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/426040",
            "namespace": "instructions",
            "key": "dry",
            "owenerType": "Product"
          }
        }
      ]
    }
  }
}

The next example uses one of the returned IDs to delete the MetafieldStorefrontVisibility that has the namespace instructions and the key wash.

mutation {
  metafieldStorefrontVisibilityDelet(id: "gid://shopify/MetafieldStorefrontVisibility/426040") {
    deletedMetafieldStorefrontVisibilityId
    userErrors {
      field
      message
    }
  }
}

{
  "data": {
    "deletedMetafieldStorefrontVisibilityId": "gid://shopify/MetafieldStorefrontVisibility/426040",
    "userErrors": []
  }
}

All product metafields that have namespace instructions and the key wash are now hidden from the Storefront API.

Related topics

• Metafield reference for the Storefront API
• Metafield reference for the REST Admin API
• Metafield reference for the GraphQL Admin API
• Metafield reference for Liquid