--- title: Retrieve metafields with the Storefront API description: Learn how to retrieve metafields with the Storefront API to access additional information from different types of resources. source_url: html: https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields md: https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields.md --- ExpandOn this page * [Requirements](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#requirements) * [Step 1: Expose metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-1-expose-metafields) * [Step 2: Retrieve metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-2-retrieve-metafields) * [Step 3: Hide metafields (optional)](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-3-hide-metafields-optional) * [Next steps](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#next-steps) # Retrieve metafields with the Storefront API You can retrieve metafields with the [Storefront API](https://shopify.dev/docs/api/storefront) 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. *** ## Requirements * You've completed the [Getting started with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/getting-started) guide. * You're familiar with [querying products and collections](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/getting-started). - You've created [resources that support metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections#retrieving-metafields) in your store, and you've [created metafields](https://shopify.dev/docs/apps/build/custom-data/metafields/manage-metafields#step-1-create-a-metafield) for those resources. - You're familiar with [how metafields work](https://shopify.dev/docs/apps/build/custom-data/metafields). Note 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/metafield). *** ## Step 1: Expose metafields Important As of API version 2025-01, the `metafieldStorefrontVisibilityCreate` mutation has been removed. Use metafield definitions with the `access.storefront` parameter instead. 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafielddefinitioncreate) or [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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. ### Creating 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: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { metafieldDefinitionCreate( definition: { namespace: "testapp" key: "pizza-size-inches" name: "Pizza Size (inches)" type: "number_integer" ownerType: PRODUCT access: { storefront: "PUBLIC_READ" } } ) { createdDefinition { id namespace key access { storefront } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "metafieldDefinitionCreate": { "createdDefinition": { "id": "gid://shopify/MetafieldDefinition/123456", "namespace": "testapp", "key": "pizza-size-inches", "access": { "storefront": "PUBLIC_READ" } }, "userErrors": [] } } } ``` You can create multiple metafield definitions. Here's another example for an expiration date metafield: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { metafieldDefinitionCreate( definition: { namespace: "testapp" key: "expiration-date" name: "Expiration Date" type: "date" ownerType: PRODUCT access: { storefront: "PUBLIC_READ" } } ) { createdDefinition { id namespace key access { storefront } } userErrors { field message } } } ``` ### Updating 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: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { metafieldDefinitionUpdate( definition: { access: { storefront: "PUBLIC_READ" } } id: "gid://shopify/MetafieldDefinition/123456" ) { updatedDefinition { id namespace key access { storefront } } userErrors { field message } } } ``` *** ## Step 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. Note If you have existing metafields that were previously exposed using the deprecated `metafieldStorefrontVisibilityCreate` mutation, you'll need to create or update their metafield definitions with `access.storefront` set to `"PUBLIC_READ"` to maintain Storefront API access. 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 https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { product(handle: "amazing-frozen-pizza") { pizzaSizeInches: metafield(namespace: "testapp", key: "pizza-size-inches") { value type } expirationDate: metafield(namespace: "testapp", key: "expiration-date") { value type } } } ``` ## JSON response ```json { "data": { "product": { "pizzaSizeInches": { "value": "9", "type": "number_integer" }, "expirationDate": { "value": "2025-12-31", "type": "date" } } } } ``` *** ## 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { metafieldDefinitions(first: 5, namespace: "testapp", ownerType: PRODUCT) { edges { node { id namespace key ownerType access { storefront } } } } } ``` ## JSON response ```json { "data": { "metafieldDefinitions": { "edges": [ { "node": { "id": "gid://shopify/MetafieldDefinition/123456", "namespace": "testapp", "key": "pizza-size-inches", "ownerType": "PRODUCT", "access": { "storefront": "PUBLIC_READ" } } }, { "node": { "id": "gid://shopify/MetafieldDefinition/123457", "namespace": "testapp", "key": "expiration-date", "ownerType": "PRODUCT", "access": { "storefront": "PUBLIC_READ" } } } ] } } } ``` 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`: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { metafieldDefinitionUpdate( definition: { access: { storefront: "NONE" } } id: "gid://shopify/MetafieldDefinition/123456" ) { updatedDefinition { id namespace key access { storefront } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "metafieldDefinitionUpdate": { "updatedDefinition": { "id": "gid://shopify/MetafieldDefinition/123456", "namespace": "testapp", "key": "pizza-size-inches", "access": { "storefront": "NONE" } }, "userErrors": [] } } } ``` *** ## Next steps * Learn how to [use metafields](https://shopify.dev/docs/apps/build/custom-data/metafields) to store information related to your app and attach that information to Shopify API resources. * Explore the [metafield reference for the Storefront API](https://shopify.dev/docs/api/storefront/latest/objects/metafield). *** * [Requirements](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#requirements) * [Step 1: Expose metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-1-expose-metafields) * [Step 2: Retrieve metafields](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-2-retrieve-metafields) * [Step 3: Hide metafields (optional)](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#step-3-hide-metafields-optional) * [Next steps](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields#next-steps)