---
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
api_name: storefront
---

# 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).

***