Conditional metafield definitions

Constraints allow metafield definitions to be applied to a subset of resources.

Anchor to How it worksHow it works

By default, metafield definitions apply to every resource on their owner type. For example, Product metafield definitions apply to all products and appear on all product detail pages in the Shopify admin.

However, some metafield definitions should only apply to a subset of resources. For example, Shoe size is a valid metafield for Shoes products but wouldn't apply to Sweaters.

Metafield definition constraints provide a way to conditionally apply definitions based on the characteristics of a resource. For example, each standard category metafield comes with a set of constraints, which determine what product categories the metafield applies to.

At the core of the conditional metafields system are constraint subtypes. Constraint subtypes are key | value pairs that identify a "subtype" of a metafield owner type.

For example, because gid://shopify/TaxonomyCategory/aa-8 is the ID of the Shoes product category, the Shoes constraint subtype is identified by:

Currently, Shopify only supports constraint subtypes that correspond to product categories on Product metafield definitions. These constraint subtypes all have a key equal to category.

Anchor to ExamplesExamples

Anchor to Find product category IDs for constraints inputsFind product category IDs for constraints inputs

You might want to create a custom Shoelace material conditional metafield that applies to Shoes and the children categories of Shoes, such as Boots and Sneakers.

You need to determine the IDs of the Shoes category and its children. This data can be extracted directly from our product-taxonomy repository.

Alternatively, you can determine taxonomy category IDs using the GraphQL Admin API. For example, if you know that the ID for Shoes is gid://shopify/TaxonomyCategory/aa-8, then you can find the IDs for the children of Shoes using the following query:

Anchor to Create a custom conditional metafield definitionCreate a custom conditional metafield definition

You can then use the constraints field on metafieldDefinitionCreate to create the conditional metafield.

Anchor to Add & remove constraints on a metafield definitionAdd & remove constraints on a metafield definition

If you would like to edit the constraints of a metafield definition, you can use the constraintsUpdates field on metafieldDefinitionUpdate.

The constraintsUpdates field handles both the creation and deletion of constraints. For example, you might realize that Shoelace material doesn't make sense on your Flats products because Flats don't have shoelaces. You might have also started selling a line of Shoelaces products and would like to track the Shoelace material of these new products.

The following example shows how you could update the Shoelace material metafield so that it is no longer constrained to Flats but is added to Shoelaces.

Anchor to Unconstrain a metafield definitionUnconstrain a metafield definition

If you no longer want a definition to be constrained, then you can also use the constraintsUpdates field to remove all of the definition's constraints. The constraints can be identified individually or you can set both the key and values fields to null to delete all constraints.

If a definition is unconstrained, then the definition applies to all resources and appears on all resource pages in the Shopify admin.

Anchor to Query for metafield definitions based on constraintsQuery for metafield definitions based on constraints

The constraintSubtype and constraintStatus arguments can be used to filter metafield definitions queries based on constraints.

The constraintSubtype argument returns only metafield definitions that apply to the identified subtype. Metafield definitions are applicable to a constraint subtype if one of the following criteria is met:

• The metafield definition has a constraint matching the constraintSubtype.

• The metafield definition does not have any constraints, which means the definition applies to all constraint subtypes.

  The constraintStatus argument filters metafields based on whether they are constrained or unconstrained. constraintStatus accepts the following values:

• CONSTRAINED_ONLY

• UNCONSTRAINED_ONLY

• CONSTRAINED_AND_UNCONSTRAINED

  constraintSubtype and constraintStatus can also be used on the standardMetafieldDefinitionTemplates query in order to query metafield standard templates based on their constraints.