---
title: Use metafield capabilities
description: Learn about optional features available for metafields.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities'
  md: 'https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md'
---

# Use metafield capabilities

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

* **[`smartCollectionCondition`](#smart-collection)**: Create an automated collection based on metafield values for a given definition.
* **[`adminFilterable`](#admin-filterable)**: Filter supported owner types based on metafield values for a definition in the Shopify admin and GraphQL Admin API.
* **[`uniqueValues`](#unique-values)**: Enforce unique metafield values for a definition.
* **[`cartToOrderCopyable`](#cart-to-order-copyable)**: Automatically copy cart metafield values to corresponding order metafields when an order is created.

**Capability support in TOML configuration:**

Currently, only the `adminFilterable`, `uniqueValues`, and `cartToOrderCopyable` capabilities are supported in TOML configuration.

***

## Smart 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 type | Supported conditions |
| - | - |
| True or false | equals |
| Integer | equals greater than less than |
| Decimal | equals greater than less than |
| Rating | equals greater than less than |
| Single line text | equals |
| Metaobject reference | equals |

### Enabling the smart collection capability

Enable this capability using either:

* [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate)
* [`metafieldDefinitionCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)

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

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

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

## Variables

```json
{
  "definition": {
    "namespace": "custom",
    "key": "material",
    "ownerType": "PRODUCT",
    "capabilities": {
      "smartCollectionCondition": {
        "enabled": true
      }
    }
  }
}
```

### Using 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate) mutation.
* To update an existing collection, you can use the [`collectionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate) mutation.

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

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

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

## Variables

```json
{
  "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"
        }
      ]
    }
  }
}
```

***

## Admin 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](https://shopify.dev/docs/apps/build/metafields/query-using-metafields).

Admin filterable is available for the following resources:

| Resource Type |
| - |
| Products |
| Companies\* |
| Company Locations\* |
| Metaobjects |
| Orders |

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

**Info:**

Admin Filterable is available for all metafield types EXCEPT JSON and rich text.

To enable this capability, you can use TOML configuration or the [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate) mutation.

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

## shopify.app.toml

##### TOML

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

##### GraphQL

```graphql
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](https://shopify.dev/docs/apps/build/metafields/query-using-metafields) for examples of filtering by metafield value.

***

## Unique 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](https://shopify.dev/docs/apps/build/metafields/working-with-custom-ids) for a complete guide.

| Metafield Type |
| - |
| Single line text |
| URL |
| Integer |

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

## shopify.app.toml

##### TOML

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

##### GraphQL

```graphql
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
    }
  }
}
```

***

## Cart 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](https://shopify.dev/docs/api/storefront/latest/input-objects/CartInputMetafieldInput) or with the [Checkout UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets).

**Info:**

Only available for order metafield definitions.

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

## shopify.app.toml

##### TOML

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

##### GraphQL

```graphql
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
    }
  }
}
```

***