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
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.
The existing deprecated value types will continue to be allowed when creating new metafields with the new
This section will guide you through the following steps:
Migrate your metafields in the REST API
- Change the
metafieldresource, as seen below:
Migrate your metafields in the GraphQL API
- Change the
metafieldobject, as seen below:
Known issues for metafield types
When using the REST Admin API version
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
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.
When you query a resource, you can retrieve its metafields.
metafield field to return a single metafield. Specify the metafield that you want to retrieve by using the
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.
Use the metafieldDelete mutation to delete a metafield. Specify the metafield that you want to delete by including its ID in the mutation input.