Retrieve metafields with the Storefront API

You can retrieve metafields with the Storefront API to access additional information from different types of resources.

This tutorial describes how to expose, retrieve, and hide metafields with the Storefront API.

Requirements

Limitations

You can't create, update, or delete metafields with the Storefront API.

If you want to perform these types of operations on metafields, then you need to use the GraphQL Admin API or the REST Admin API.

Resources that support metafields

The following table lists the resources that are available on the Storefront API that support metafields:

Resource Description
Article An article in an online store blog.
Blog An online store blog.
Collection A grouping of products.
Customer A customer account with the store. Customer accounts store contact information for the customer, saving logged-in customers the trouble of having to provide it at every checkout.
Order A customer's request to purchase one or more products from a store.
Page A page to hold static HTML content. Each Page object represents a custom page on the online store.
Product An individual item for sale in a Shopify store.
ProductVariant A different version of a product, such as differing sizes or differing colors.
Shop A collection of the general settings and information about a store.

Expose metafields

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. For each metafield that you want to expose, 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.

MetafieldStorefrontVisibility records

Each MetafieldStorefrontVisibility record exposes 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.

Example

The following example creates a MetafieldStorefrontVisibility record that exposes all product metafields that have the namespace testapp and the key pizza-size-inches:

POST /admin/api/2021-10/graphql.json

Variables

JSON response

Any product metafield with the namespace testapp and the key pizza-size-inches will now be visible to the Storefront API.

Retrieve metafields

After exposing metafields, you can retrieve them with the Storefront API by 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.

In the following example, you have a product called “Amazing Frozen Pizza” and you've created metafields that store the size of the pizza and the pizza's expiration date. You want to display those values on the storefront according to each metafield's type. The following example shows how to retrieve the value and type for each metafield using the Storefront API.

POST /api/unstable/graphql.json

JSON response

Hide metafields

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.

Examples

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

POST /admin/api/2021-10/graphql.json

JSON response

The next example uses one of the returned IDs to delete the MetafieldStorefrontVisibility that has the namespace testapp and the key pizza-size-inches.

POST /admin/api/2020-10/graphql.json

JSON response

All product metafields that have namespace testapp and the key pizza-size-inches are now hidden from the Storefront API.

Next steps