Metafield definitions

Metafield definitions enable you to create additional validation constraints for metafields, and enable the merchant to edit metafield values in context. Where possible, you should adopt standard metafields, so that your app can access information that merchants have already stored in standard metafields. You can also create your own custom metafield definitions.

If you want to create and manage metafield definitions with your app, then you can use the GraphQL Admin API as described on this page. 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.

Structure of a metafield definition

A metafield definition includes the following information:

• Name: A human-readable name for the definition.
• Namespace and key: A namespace and key to identify and group the metafield, sorted as namespace.key.
• Type: The type of data that the metafield stores.
• Owner type: The resource or resources that the metafield can be attached to. For example, you could make a metafield definition that's attached to the Product resource.
• Description (optional): A description of the metafield that's shown in the Shopify admin.
• Validation options (optional): An array of validation options for the metafield. 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.
• Presentation hints (optional): An array of presentation options for the metafield. Presentation hints allow merchants to define how they want certain metafields to render on their online store and other channels. For example, a presentation hint could be added to a boolean value to display true as Yes and false as No on the online store.

Create a metafield definition

You can create a metafield definition using the metafieldDefinitionCreate mutation. The following example displays how to add a metafield definition called "Ingredients" to the Product resource, which stores multi-line text (such as a list of ingredients used to make the product).

POST /admin/api/unstable/graphql.json

Variables

Create a metafield definition with a validation option

The following example displays how to create a metafield definition called Pizza size with a minimum size of 9 and a maximum size of 15.

POST /admin/api/unstable/graphql.json

Variables

Retrieve a metafield definition

You can retrieve a metafield definition by using its ID, as shown in the following example.

Update a metafield definition

To update a metafield definition, use the metafieldDefinitionUpdate mutation. You can update only the name and description of a metafield.

In the following example, you want to change a metafield definition's name from Pizza size to Pizza size (inches). This name is displayed to merchants in the Shopify admin.

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.