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 definitionAnchor 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
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 definitionAnchor 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):
Create a metafield definition with validation optionsAnchor 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:
Retrieve a metafield definitionAnchor link to section titled "Retrieve a metafield definition"
The following example retrieves a metafield definition by using its ID:
Update a metafield definitionAnchor 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):
Delete a metafield definitionAnchor 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.