Use metafield capabilities

Capabilities enable 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.
• cartToOrderCopyable: Automatically copy cart metafield values to corresponding order metafields when an order is created.

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:

Anchor to Enabling the smart collection capabilityEnabling the smart collection capability

Enable this capability using either:

• metafieldDefinitionUpdate
• metafieldDefinitionCreate

The following example shows how to update a metafield definition with the smartCollectionCondition set to true to enable the smart collection capability:

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.

The following example creates a smart collection that includes products with a color metaobject reference set to blue:

Anchor to Admin filterableAdmin filterable

The Shopify 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 developers to find and manage resources, such as products, based on their specific metafield values. Learn how to query using metafields.

Admin filterable is available for the following resources:

*Does not support numeric and date searches at this time.

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

The following example shows how to enable the admin filterable capability:

[product.metafields.custom.material]
name = "material"
type = "single_line_text_field"
capabilities.admin_filterable = true

mutation metafieldDefinitionUpdate {
  metafieldDefinitionUpdate(definition: {
    namespace: "custom"
    key: "material"
    ownerType: PRODUCT
    capabilities: {
      adminFilterable: {
        enabled: true
      }
    }
  }) {
    userErrors {
      field
      message
    }
    updatedDefinition {
      key
      name
      namespace
      ownerType
      id
      capabilities {
        adminFilterable {
          enabled
        }
      }
    }
  }
}

See query using metafields for examples of filtering by metafield value.

Anchor to Unique valuesUnique values

The unique values capability ensures all values of a metafield definition are unique. This is commonly used when storing external identifiers that must not duplicate, like ERP or PIM IDs. See working with custom IDs for a complete guide.

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

[product.metafields.custom.external_id]
name = "External ID"
type = "single_line_text_field"
capabilities.unique_values = true

mutation {
  metafieldDefinitionCreate(definition: {
    name: "External ID"
    namespace: "custom"
    key: "external_id"
    type: "single_line_text_field"
    ownerType: PRODUCT
    capabilities: {
      uniqueValues: {
        enabled: true
      }
    }
  }) {
    createdDefinition {
      id
      name
      namespace
      key
      capabilities {
        uniqueValues {
          enabled
        }
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Anchor to Cart to order copyableCart to order copyable

You can automatically copy the value from a cart metafield to the corresponding order metafield when an order is created. The namespace and key must match between the cart and order metafields.

You can set cart metafields with the Storefront API or with the Checkout UI Extensions.

The following example shows how to enable the cart to order copyable capability:

[order.metafields.custom.gift_message]
name = "Gift Message"
type = "single_line_text_field"
capabilities.cart_to_order_copyable = true

mutation {
  metafieldDefinitionCreate(definition: {
    name: "Gift Message"
    namespace: "custom"
    key: "gift_message"
    type: "single_line_text_field"
    ownerType: ORDER
    capabilities: {
      cartToOrderCopyable: {
        enabled: true
      }
    }
  }) {
    createdDefinition {
      id
      name
      namespace
      key
      capabilities {
        cartToOrderCopyable {
          enabled
        }
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}