Retrieving metafields using 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:

Field Description
namespace A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from clashing with others.
key The identifier for the metafield value.
value The information to be stored by the metafield.
valueType The information type of the metafield's value. Valid values are STRING, INTEGER, and JSON_STRING.

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.

A product has two metafields: Metafield 1 and Metafield 2. Only Metafield 1 has a MetafieldStorefrontVisibility record. The Admin API can read both metafields, but the Storefront API can read only Metafield 1.

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.

POST /admin/api/2019-07/graphql.json

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

Variables

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

JSON response

{
  "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.

POST /api/2019-07/graphql.json

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

JSON response

{
  "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.

POST /api/2019-07/graphql.json

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

JSON response

{
  "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.

POST /admin/api/2019-07/graphql.json

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

JSON response

{
  "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.

POST /admin/api/2019-07/graphql.json

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

JSON response

{
  "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.

Sign up for a Partner account to get started.

Sign up