Skip to main content

Use metafield capabilities

Capabilities power optional features for metafield definitions. You can enable the following capabilities:

  • smartCollectionCondition: Create an automated collection based on metafield values for a given definition.
  • adminFilterable: Filter supported owner types based on metafield values for a definition in the Shopify admin and GraphQL Admin API.
  • uniqueValues: Enforce unique metafield values for a definition.

Anchor to Smart collectionSmart collection

An automated collection, also known as a smart collection, is a grouping of products that's defined by a set of rules. Shopify automatically changes the contents of an automated collection based on the configured rules. You can create rules with metafield definitions to automatically update the contents of an automated collection based on product or variant metafields.

Smart collections are available for the following metafield types:

Metafield definition typeSupported conditions
True or falseequals
Integerequals
greater than
less than
Decimalequals
greater than
less than
Ratingequals
greater than
less than
Single line textequals
Metaobject referenceequals

Anchor to Enabling the smart collection capabilityEnabling the smart collection capability

Enable this capability using either:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation metafieldDefinitionUpdate($definition: MetafieldDefinitionUpdateInput!) {
metafieldDefinitionUpdate(definition: $definition) {
userErrors {
field
message
}
updatedDefinition {
key
name
namespace
ownerType
id
capabilities {
smartCollectionCondition {
enabled
}
}
}
}
}

Variables

{
"definition": {
"namespace": "custom",
"key": "material",
"name": "material",
"ownerType": "PRODUCT",
"type": "single_line_text_field",
"capabilities": {
"smartCollectionCondition": {
"enabled": true
}
}
}
}

Anchor to Using metafields in a smart collectionUsing metafields in a smart collection

After the capability is enabled, you can create a smart collection either in the Shopify admin or with the following mutations:

  • To create a smart collection, you can use the collectionCreate mutation.

  • To update an existing collection, you can use the collectionUpdate mutation.

    In the following example, the smart collection is set to include products that have a metafield definition of type metaobject reference with the metaobject representing blue, from the standard color metafield definition.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation CreateCollection($collection: CollectionInput!) {
collectionCreate(input: $collection) {
collection {
id
title
descriptionHtml
sortOrder
handle
templateSuffix
ruleSet {
appliedDisjunctively
rules {
column
relation
condition
}
}
}
userErrors {
field
message
}
}
}

Variables

{
"collection": {
"title": "Blue products collection",
"metafields": [],
"ruleSet": {
"appliedDisjunctively": false,
"rules": [
{
"column": "PRODUCT_METAFIELD_DEFINITION",
"relation": "EQUALS",
"condition": "gid://shopify/Metaobject/112030056537",
"conditionObjectId": "gid://shopify/MetafieldDefinition/23417389145"
}
]
}
}
}

Anchor to Admin filterableAdmin filterable

The admin filterable capability allows you to use a metafield definition and its values to filter resource lists in the Shopify admin. This capability makes it easier for merchants to find and manage resources such as products based on their specific metafield values. A more detailed guide is available.

The capability is available for the following metafield types:

Metafield Type
True or false
Single line text
Single line text (list)
Product reference
Product reference (list)
Collection reference
Collection reference (list)
Page reference
Page reference (list)
Metaobject reference
Metaobject reference (list)
Company reference
Company reference (list)

To enable this capability, you can use the metafieldDefinitionUpdate mutation.

The following example shows how to create a metafield definition with adminFilterable set to true to enable the admin filterable capability:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation metafieldDefinitionUpdate($definition: MetafieldDefinitionUpdateInput!) {
metafieldDefinitionUpdate(definition: $definition) {
userErrors {
field
message
}
updatedDefinition {
key
name
namespace
ownerType
id
capabilities {
adminFilterable {
enabled
}
}
}
}
}

Variables

{
"definition": {
"namespace": "custom",
"key": "material",
"name": "material",
"ownerType": "PRODUCT",
"type": "single_line_text_field",
"capabilities": {
"adminFilterable": {
"enabled": true
}
}
}
}

Anchor to Using metafields to filter productsUsing metafields to filter products

When the admin filterable capability is enabled, you can filter products based on a metafield definition value. In the following example, the query returns products that have a metafield definition value of blue for the color standard metafield definition.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

query Products {
products (first: 10, query: "metafields.shopify.color-pattern:\"9047670806\"") {
edges {
node {
id
title
handle
}
}
}
}

Anchor to Unique valuesUnique values

The unique values capability ensures all values of a metafield definition are unique. This capability is only available for single_line_text_field, url, and integer definition types. A more detailed guide is available.

Anchor to LimitationsLimitations

You can only enable the unique values capability on new definitions or definitions without existing metafields.

Anchor to ExampleExample

The following example shows how to create a metafield definition with uniqueValues set to enabled to enable the unique values capability.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
metafieldDefinitionCreate(definition: $definition) {
createdDefinition {
id
name
namespace
key
capabilities {
uniqueValues {
enabled
}
}
}
userErrors {
field
message
code
}
}
}

Variables

{
"definition": {
"name": "My Unique Field",
"namespace": "custom",
"key": "field",
"description": "A custom field with unique values",
"type": "single_line_text_field",
"ownerType": "PRODUCT",
"capabilities": {
"uniqueValues": {
"enabled": true
}
},
"pin": true
}
}
Was this page helpful?