Retrieve metafields with the Storefront API

You can retrieve metafields with the Storefront API to access additional information from different types of resources. This guide describes how to expose metafields to the Storefront API, retrieve them, and hide them from the Storefront API.

Anchor to RequirementsRequirements

• You've completed the Getting started with the Storefront API guide.
• You're familiar with querying products and collections.

• You've created resources that support metafields in your store, and you've created metafields for those resources.
• You're familiar with how metafields work.

Anchor to Step 1: Expose metafieldsStep 1: Expose metafields

To expose metafields to the Storefront API, you need to create or update a metafield definition with the access.storefront parameter set to "PUBLIC_READ". This can be done using the metafieldDefinitionCreate or metafieldDefinitionUpdate mutations in the GraphQL Admin API.

The following fields are required when creating a metafield definition:

• namespace — The namespace for the metafield.
• key — The key for the metafield.
• name — A human-readable name for the metafield.
• type — The metafield type (e.g., single_line_text_field, number_integer).
• ownerType — The resource that owns this metafield (e.g., PRODUCT).
• access.storefront — Set to "PUBLIC_READ" to expose to the Storefront API.

Anchor to Creating a new metafield definitionCreating a new metafield definition

The following example creates a metafield definition for a product metafield with the namespace testapp and the key pizza-size-inches, making it accessible via the Storefront API:

You can create multiple metafield definitions. Here's another example for an expiration date metafield:

Anchor to Updating an existing metafield definitionUpdating an existing metafield definition

If you have an existing metafield definition that needs to be exposed to the Storefront API, you can update it using the metafieldDefinitionUpdate mutation:

Anchor to Step 2: Retrieve metafieldsStep 2: 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.

Anchor to Step 3: Hide metafields (optional)Step 3: Hide metafields (optional)

If you no longer need to access a metafield with the Storefront API, you can hide it by updating the metafield definition to remove storefront access.

To hide a metafield from the Storefront API, use the metafieldDefinitionUpdate mutation and set access.storefront to "NONE" or simply omit the storefront access.

First, you can retrieve your metafield definitions to find the one you want to update:

The following example uses one of the returned IDs to update the metafield definition to remove storefront access for the metafield with namespace testapp and key pizza-size-inches:

Anchor to Next stepsNext steps

• Learn how to use metafields to store information related to your app and attach that information to Shopify API resources.
• Explore the metafield reference for the Storefront API.