Metafield definitions
Metafield definitions enable you to include data validation for metafields, and enable merchants to add metafield values for resources in the Shopify admin. We also provide standard metafield definitions for common use cases. Using standard definitions means that your app can access information that merchants might have already stored in these metafields and provides interoperability across the Shopify platform.
If you want to create and manage custom metafield definitions with your app, then you can use the GraphQL Admin API as described in the following sections. If you're helping a merchant to build their store, and you want to set up metafields in the Shopify admin, then refer to the merchant documentation about metafields.
Metafield definitions are available in GraphQL Admin API version 2021-10 or later.
Parts of a metafield definition
Anchor link to section titled "Parts of a metafield definition"A metafield definition includes the following information:
- Namespace: A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name.
- Key: The name for the metafield.
Type: The type of data that the metafield stores.
Name: A human-readable name for the metafield definition. The name is displayed to merchants in the Shopify admin.
Description (optional): A description of the metafield definition. The description is displayed to merchants in the Shopify admin.
Owner type: The resource that the metafield is attached to. Owner types include
ARTICLE,BLOG,COLLECTION,CUSTOMER,DRAFTORDER,ORDER,PAGE,PRODUCT,PRODUCTIMAGE,PRODUCTVARIANT, andSHOP(default).Validation options (optional): An array of validation options for the metafield value. For example, for a metafield with the type
date, you can set a minimum date validation, so that the metafield can store only dates after a specific date.
Create a metafield definition
Anchor link to section titled "Create a metafield definition"You can create a metafield definition using the metafieldDefinitionCreate mutation. The following example creates a metafield definition called "Ingredients" for the PRODUCT resource, which stores multi-line text (such as a list of ingredients used to make the product):
POST /admin/api/2022-07/graphql.json
Variables
JSON response
Create a metafield definition with validation options
Anchor link to section titled "Create a metafield definition with validation options"The following example creates a metafield definition called Pizza size with validation for the metafield to have a minimum size of 9 inches and a maximum size of 15 inches:
POST /admin/api/2022-07/graphql.json
Variables
JSON response
Retrieve a metafield definition
Anchor link to section titled "Retrieve a metafield definition"The following example retrieves a metafield definition by using its ID:
POST /admin/api/2022-07/graphql.json
JSON response
Update a metafield definition
Anchor link to section titled "Update a metafield definition"You can use the metafieldDefinitionUpdate mutation to update a metafield definition. You can update only the name and description of a metafield.
The following example changes a metafield definition's name from Pizza size to Pizza size (inches):
POST /admin/api/2022-07/graphql.json
Variables
JSON response
Delete a metafield definition
Anchor link to section titled "Delete a metafield definition"To delete a metafield definition, use the metafieldDefinitionDelete mutation. You can also set an option that, when selected, deletes all metafields that use that definition.
The following example deletes the metafield definition for bakery.ingredients, and also deletes all metafields that use the definition.
POST /admin/api/2022-07/graphql.json
JSON response