---
title: Manage metafield definitions
description: Learn how to manage metafield definitions.
source_url:
  html: https://shopify.dev/docs/apps/build/custom-data/metafields/definitions
  md: https://shopify.dev/docs/apps/build/custom-data/metafields/definitions.md
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#requirements)
* [Step 1: Create a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-1-create-a-metafield-definition)
* [Step 2: Retrieve a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-2-retrieve-a-metafield-definition)
* [Step 3: Update a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-3-update-a-metafield-definition)
* [Step 4 (Optional): Delete a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-4-optional-delete-a-metafield-definition)
* [Next steps](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#next-steps)

# Manage metafield definitions

[Metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions) enable you to include data validation for metafields, and enable users to add metafield values for resources in the Shopify admin. This guide shows you how to manage metafield definitions using TOML and the GraphQL Admin API.

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
* Your app has access to the [owner type](https://shopify.dev/docs/api/admin-graphql/latest/enums/metafieldownertype) that you want to associate with the metafield definition. You can only create metafield definitions for owner types that you have access to.

***

## Step 1: Create a metafield definition

You can create a metafield definition using declarative TOML configuration or the GraphQL Admin API.

TOML configuration only works with the App-reserved namespace

You can only declare metafield and metaobject definitions in the app-reserved namespace `$app` to ensure that only the owning app can make changes to definitions. This constraint allows Shopify to guarantee a consistent state between all shops your app is installed on. App-reserved sub-namespaces are supported using `[product.metafields.feature_x.configuration]`.

Additionally, definitions created in TOML are read-only through the Admin API, and can only be updated or deleted through the TOML configuration file.

The following example creates a metafield definition called `Ingredients` for the `PRODUCT` owner type, which stores multi-line text, such as a list of ingredients used to make the product.

Note that the TOML example uses the `app` namespace (required for TOML), while the GraphQL example uses a custom `bakery` namespace (GraphQL allows any namespace).

## shopify.app.toml

```toml
[metafields]
api_version = "2025-01"  # or your current API version


[product.metafields.app.ingredients]
name = "Ingredients"
description = "A list of ingredients used to make the product."
type = "multi_line_text_field"
```

```graphql
mutation CreateMetafieldDefinition {
  metafieldDefinitionCreate(definition: {
    name: "Ingredients"
    namespace: "bakery"
    key: "ingredients"
    description: "A list of ingredients used to make the product."
    type: "multi_line_text_field"
    ownerType: PRODUCT
  }) {
    createdDefinition {
      id
      name
      namespace
      key
      # add other return fields
    }
    userErrors {
      field
      message
      code
    }
  }
}
```

***

## Step 2: Retrieve a metafield definition

You can use the [`metafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition) query to retrieve a metafield definition.

The following example retrieves a metafield definition by using its ID:

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

## GraphQL query

```graphql
{
  metafieldDefinition(id: $id) {
    name
    namespace
    key
    description
    ownerType
    type {
      name
    }
  }
}
```

## Variables

```json
{
  "id": "gid://shopify/MetafieldDefinition/18776120"
}
```

## JSON response

```json
{
  "data": {
    "metafieldDefinition": {
      "name": "Expiry Date",
      "namespace": "food",
      "key": "expiry_date",
      "description": "The expiry date.",
      "ownerType": "PRODUCT",
      "type": {
        "name": "date"
      }
    }
  }
}
```

***

## Step 3: Update a metafield definition

You can update a metafield definition using TOML configuration or the GraphQL Admin API. You can update only the name and description of a metafield definition.

The following example changes a metafield definition's name from `Pizza size` to `Pizza size (inches)`:

## shopify.app.toml

```toml
[metafields]
api_version = "2025-01"  # or your current API version


[product.metafields.app.pizzasize]
name = "Pizza size (inches)"
```

```graphql
mutation UpdateMetafieldDefinition {
  metafieldDefinitionUpdate(definition: {
    name: "Pizza size (inches)"
    namespace: "bakery"
    key: "pizzasize"
    ownerType: PRODUCT
  }) {
    updatedDefinition {
      id
      name
      namespace
      key
      # add other return fields
    }
    userErrors {
      field
      message
      code
    }
  }
}
```

***

## Step 4 (Optional): Delete a metafield definition

You can delete a metafield definition using TOML configuration or the GraphQL Admin API.

With **TOML configuration**, deleting a metafield definition is as simple as removing the corresponding lines from your `shopify.app.toml` file and running `shopify app deploy`. For example, to delete the `app.ingredients` definition, you would remove:

```toml
[product.metafields.app.ingredients]
name = "Ingredients"
description = "A list of ingredients used to make the product."
type = "multi_line_text_field"
```

With the **GraphQL Admin API**, you can use the [`metafieldDefinitionDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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` (via GraphQL) or `app.ingredients` (via TOML), and also deletes all metafields that use the definition.

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

## GraphQL mutation

```graphql
mutation DeleteMetafieldDefinition {
  metafieldDefinitionDelete(id: $id, deleteAllAssociatedMetafields: $deleteAllAssociatedMetafields) {
    deletedDefinitionId
    userErrors {
      field
      message
      code
    }
  }
}
```

## Variables

```json
{
  "id": "gid://shopify/MetafieldDefinition/18710584",
  "deleteAllAssociatedMetafields": true
}
```

## JSON response

```json
{
  "metafieldDefinitionDelete": {
    "deletedDefinitionId": "gid://shopify/MetafieldDefinition/18710584",
    "userErrors": []
  }
}
```

***

## Next steps

* Learn how to [manage validation options](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-validation-options) using the GraphQL Admin API.
* Learn how to [create automated collections](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities#smart-collection) with metafield definition conditions.

***

* [Requirements](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#requirements)
* [Step 1: Create a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-1-create-a-metafield-definition)
* [Step 2: Retrieve a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-2-retrieve-a-metafield-definition)
* [Step 3: Update a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-3-update-a-metafield-definition)
* [Step 4 (Optional): Delete a metafield definition](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#step-4-optional-delete-a-metafield-definition)
* [Next steps](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions#next-steps)