Managing metafields

Using the GraphQL Admin API, you can add metafields and private metafields to Shopify resources, such as a product, customer, or blog post. To learn how to create and manage metafields using the REST Admin API, refer to the REST Admin API Metafield reference.

This guide explains how to create and manage metafields, but not metafield definitions. Learn more about metafield definitions.

Metafield types and value_type deprecation

As of API version 2021-07, we've introduced a new commerce-oriented type system. The new Metafield types have built-in validation and full Liquid support. In our REST API, the type property will replace the value_type property in the Metafield resource, and in our GraphQL API, the type field will replace the value_type field in the Metafield object.

To learn more about the API changes, refer to the API specific reference documentation:

For backward compatibility, metafields that were created with a new type, but queried from API version 2021-04 or earlier, will return a backward-mapped value type. For example, in the REST API, the date type maps to the STRING value type.

For more information about the new types, refer to our list of Metafield types.

Migrating from value_type to type

The existing deprecated value types will continue to be allowed when creating new metafields with the new type.

This section will guide you through the following steps:

Migrate your metafields in the REST API

  1. Change the value_type property to type in your metafield resource, as seen below:

Migrate your metafields in the GraphQL API

  1. Change the valueType field to type in your metafield object, as seen below:

Known issues for metafield types

When using the REST Admin API version 2021-07, type is available for metafields only when querying the Metafield resource directly (/admin/api/2021-07/products/PRODUCT_ID/metafields.json). When querying a resource that can contain metafields, such as the Product resource (/admin/api/2021-07/products.json), the API still uses value_type for metafields. This issue will be fixed in API version 2021-10.

Creating metafields

You can create any number of metafields for a resource, and they'll be accessible to any app (unless it's a private metafield).

To create metafields, use a GraphQL mutation to create or update the resource that you want the metafield to belong to. The following example adds a metafield to a product by using the productUpdate mutation.

POST /admin/api/2021-07/graphql.json

Variables

JSON response

Retrieving metafields

When you query a resource, you can retrieve its metafields.

Use the metafield field to return a single metafield. Specify the metafield that you want to retrieve by using the namespace and key arguments.

POST /admin/api/2021-07/graphql.json

JSON response

Updating metafields

To update a metafield, use a GraphQL mutation to update the owning resource, and include the metafield in the mutation input. Specify the owning resource and the metafields that you're updating by their IDs. The following example updates a metafield that belongs to a product by using the productUpdate mutation.

POST /admin/api/2021-07/graphql.json

Variables

JSON response

Deleting metafields

Use the metafieldDelete mutation to delete a metafield. Specify the metafield that you want to delete by including its ID in the mutation input.

POST /admin/api/2021-07/graphql.json

Variables

JSON response