Skip to main content

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

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.

Anchor to Step 1: Expose metafieldsStep 1: Expose metafields

To create a MetafieldStorefrontVisibility record, you can use the metafieldStorefrontVisibilityCreate mutation in the GraphQL Admin API. 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 exposes all product metafields that have the namespace testapp and the key pizza-size-inches:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metafieldStorefrontVisibilityCreate(
input: {
namespace: "testapp"
key: "pizza-size-inches"
ownerType: PRODUCT
}
) {
metafieldStorefrontVisibility {
id
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"metafieldStorefrontVisibilityCreate": {
"metafieldStorefrontVisibility": {
"id": "gid://shopify/MetafieldStorefrontVisibility/196664"
},
"userErrors": []
}
}
}

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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

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

{
"data": {
"productByHandle": {
"pizzaSizeInches": {
"value": "9",
"type": "number_integer"
},
"expirationDate": {
"value": "2022-06-30",
"type": "date"
}
}
}
}

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, then 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 ownerType.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

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

JSON response

{
"data": {
"metafieldStorefrontVisibilities": {
"edges": [
{
"node": {
"id": "gid://shopify/MetafieldStorefrontVisibility/393272",
"namespace": "testapp",
"key": "pizza-size-inches",
"ownerType": "Product"
}
},
{
"node": {
"id": "gid://shopify/MetafieldStorefrontVisibility/426040",
"namespace": "testapp",
"key": "expiration-date",
"ownerType": "Product"
}
}
]
}
}
}

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

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

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

JSON response

{
"data": {
"deletedMetafieldStorefrontVisibilityId": "gid://shopify/MetafieldStorefrontVisibility/426040",
"userErrors": []
}
}

Anchor to Next stepsNext steps

Was this page helpful?