**Version: 202601**

# Create metafield definition

**POST** `/openapi/2026-01/metafield_definition/:owner_resource`

Create a new metafield definition.

## Request

**Path Parameters**

- `owner_resource` string (required)

  Resource type the metafield definition is attached to:

  *   `shop`: Shop
  *   `product`: Product
  *   `product_image`: Product image
  *   `product_variant`: Product variant
  *   `order`: Order
  *   `page`: Custom page
  *   `customer`: Customer
  *   `collection`: Collection
  *   `blog`: Blog
  *   `article`: Article
  *   `app`: App

**application/json**

**Body | Example**

**Body (required)**

- `namespace` string (required)

  A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name. For example, "global"
- `key` string (required)

  The key of the metafield (unique within the namespace). For example, "color"
- `description` string

  A brief description of the metafield definition
- `type` string (required)

  Field type of the metafield:

  *   `date`: Date
  *   `date_time`: Date and time
  *   `weight`: Weight
  *   `volume`: Volume
  *   `dimension`: Dimension
  *   `integer`: Integer
  *   `number_decimal`: Decimal
  *   `file_reference`: File reference
  *   `single_line_text_field`: Single-line text
  *   `multi_line_text_field`: Multi-line text
  *   `json`: JSON
  *   `color`: Color
  *   `rating`: Rating
  *   `url`: URL
  *   `boolean`: Boolean (true or false)
  *   `string`: String
- `name` string (required)

  Name of the metafield definition

```json
{
  "namespace": "string",
  "key": "string",
  "description": "string",
  "type": "string",
  "name": "string"
}
```

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `metafield_definition` object

    The created metafield definition

    - `id` string

      The unique identifier for the metafield definition
    - `key` string

      The key of the metafield (unique within the namespace). For example, "color"
    - `name` string

      Name of the metafield definition (displayed in the admin panel)
    - `namespace` string

      A container for a group of metafields. Grouping metafields within a namespace prevents your metafields from conflicting with other metafields with the same key name. For example, "global"
    - `owner_resource` string

      Resource type the metafield definition is attached to:

      *   `shop`: Shop
      *   `product`: Product
      *   `product_image`: Product image
      *   `product_variant`: Product variant
      *   `order`: Order
      *   `page`: Custom page
      *   `customer`: Customer
      *   `collection`: Collection
      *   `blog`: Blog
      *   `article`: Article
      *   `app`: App
    - `type` string

      Field type of the metafield:

      *   `date`: Date
      *   `date_time`: Date and time
      *   `weight`: Weight
      *   `volume`: Volume
      *   `dimension`: Dimension
      *   `integer`: Integer
      *   `number_decimal`: Decimal
      *   `file_reference`: File reference
      *   `single_line_text_field`: Single-line text
      *   `multi_line_text_field`: Multi-line text
      *   `json`: JSON
      *   `color`: Color
      *   `rating`: Rating
      *   `url`: URL
      *   `boolean`: Boolean (true or false)
      *   `string`: String
    - `description` string

      A brief description of the metafield definition
    - `create_at` string

      Creation timestamp, in ISO-8601 format
    - `updated_at` string

      Last update timestamp, in ISO-8601 format

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "metafield_definition": {
      "id": "string",
      "key": "string",
      "name": "string",
      "namespace": "string",
      "owner_resource": "string",
      "type": "string",
      "description": "string",
      "create_at": "string",
      "updated_at": "string"
    }
  }
}
```