Retrieve metafields with the Storefront API
With the Storefront API, you can retrieve metafields but not create or update them. If you want to create, update, or delete metafields, then you need to use the GraphQL Admin API or the REST Admin API.
Storing data in metafields
Metafields are essentially additional fields for Shopify resources. There are four main parts to a metafield:
Field | Description |
---|---|
namespace | A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from clashing with others. |
key | The identifier for the metafield value. |
value | The information to be stored by the metafield. |
valueType | The information type of the metafield's value. Valid values are STRING , INTEGER , and JSON_STRING . |
For example, a clothing shop might use metafields to store the care instructions for its clothing products. The shop could create separate metafields for washing and drying instructions, and group them by using the namespace instructions
. The following example shows a metafield for washing instructions:
{
"date": {
"productByHandle": {
"metafield": {
"namespace": "instructions",
"key": "wash",
"value": "cold wash",
"valueType": "STRING"
}
}
}
}
The Metafield type also includes other fields, such as description
and ownerType
. To learn more, see the Metafield reference.
Expose metafields to the Storefront API
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 to allow them. For each metafield that you want to allow, you need to create a MetafieldStorefrontVisibility record.
Each MetafieldStorefrontVisibility record allows 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
.
The following example creates a MetafieldStorefrontVisibility record that allows all product metafields that have the namespace instructions
and the key wash
.
POST /admin/api/2020-10/graphql.json
mutation($input: MetafieldStorefrontVisibilityInput!) {
metafieldStorefrontVisibilityCreate(
input: $input
) {
metafieldStorefrontVisibility {
id
}
userErrors {
field
message
}
}
}
Variables
{
"input": {
"namespace": "instructions",
"key": "wash",
"ownerType": "PRODUCT"
}
}
JSON response
{
"data": {
"metafieldStorefrontVisibilityCreate": {
"metafieldStorefrontVisibility": {
"id": "gid://shopify/MetafieldStorefrontVisibility/196664"
},
"userErrors": []
}
}
}
Any product metafield with the namespace instructions
and the key wash
will now be visible to the Storefront API.
Retrieve metafields with the Storefront API
After allowing metafields, you can retrieve them with the Storefront API by using the metafields
connection or the metafield
field.
Retrieve a list of metafields
The following example uses the metafields
connection to retrieve a product's first five metafields. The query includes the optional namespace
argument to narrow the results to metafields that have the namespace instructions
.
POST /api/2020-10/graphql.json
query {
productByHandle(handle: "the-t-shirt") {
metafields(first: 5, namespace: "instructions") {
edges {
node {
key
value
}
}
}
}
}
JSON response
{
"data": {
"productByHandle": {
"metafields": {
"edges": [
{
"node": {
"key": "wash",
"value": "cold wash"
}
},
{
"node": {
"key": "dry",
"value": "tumble dry"
}
}
]
}
}
}
}
Retrieve a single metafield
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.
The following example retrieves the value of a product's metafield with the namespace instructions
and the key wash
.
POST /api/2020-10/graphql.json
query {
productByHandle(handle: "the-t-shirt") {
metafield(namespace: "instructions", key: "wash") {
value
}
}
}
JSON response
{
"data": {
"productByHandle": {
"metafield": {
"value": "cold wash"
}
}
}
}
Hide metafields from the Storefront API
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.
The following example retrieves a list of MetafieldStorefrontVisibility records. Each result returns the object's ID, namespace, key, and owner type.
POST /admin/api/2020-10/graphql.json
query {
metafieldStorefrontVisibilities(first:5, namespace: "instructions") {
edges {
node {
id
namespace
key
ownerType
}
}
}
}
JSON response
{
"data": {
"metafieldStorefrontVisibilities": {
"edges": [
{
"node": {
"id": "gid://shopify/MetafieldStorefrontVisibility/393272",
"namespace": "instructions",
"key": "wash",
"ownerType": "Product"
}
},
{
"node": {
"id": "gid://shopify/MetafieldStorefrontVisibility/426040",
"namespace": "instructions",
"key": "dry",
"ownerType": "Product"
}
}
]
}
}
}
The next example uses one of the returned IDs to delete the MetafieldStorefrontVisibility that has the namespace instructions
and the key wash
.
POST /admin/api/2020-10/graphql.json
mutation {
metafieldStorefrontVisibilityDelete(id: "gid://shopify/MetafieldStorefrontVisibility/426040") {
deletedMetafieldStorefrontVisibilityId
userErrors {
field
message
}
}
}
JSON response
{
"data": {
"deletedMetafieldStorefrontVisibilityId": "gid://shopify/MetafieldStorefrontVisibility/426040",
"userErrors": []
}
}
All product metafields that have namespace instructions
and the key wash
are now hidden from the Storefront API.