Create shop metafield

POST 
/openapi/2025-06/metafields-shop

The Create Shop Metafield API allows developers to create a new metafield for a shop. This endpoint requires the meta field data in the request body.

Request

application/json

Body

Bodyrequired

namespacestringrequired

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"

keystringrequired

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

typestringrequired
Metafield value type:
• JSON: JSON value
• string: String value
valueGoogleProtobufValuerequired

The value of the metafield; its data type is determined by the type field. For example, "red"

descriptionstring

A brief description of the metafield. For example, "The color of the product"

definition_idstring

The ID of the associated metafield definition. For example, "123456"

Example

{
  "namespace": "string",
  "key": "string",
  "type": "string",
  "description": "string",
  "definition_id": "string"
}

Responses

200

OK

application/json

Schema

Schema

codestring

error code

messagestring

error message

data object

metafield object

The created metafield

idstring

The unique identifier for the metafield

store_iduint32

The ID of the store that owns the metafield

owner_resourcestring

Resource type the metafield 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

owner_idstring

The ID of the resource the metafield is attached to. For example, the product ID

namespacestring

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"

keystring

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

typestring

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

valueGoogleProtobufValue

The value of the metafield; its data type is determined by the type field. For example, "red"

descriptionstring

A brief description of the metafield. For example, "The color of the product"

definition_iduint64

The ID of the associated metafield definition. For example, "123456"

created_atstring

The time when the metafield was created, in ISO-8601 format

updated_atstring

The time when the metafield was last updated, in ISO-8601 format

Example

{
  "code": "string",
  "message": "string",
  "data": {
    "metafield": {
      "id": "string",
      "store_id": 0,
      "owner_resource": "string",
      "owner_id": "string",
      "namespace": "string",
      "key": "string",
      "type": "string",
      "description": "string",
      "definition_id": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  }
}