Create a metafield definition
Create a typed, validated metafield definition with metafieldDefinitionCreate, pin it in the admin and expose it to the Storefront API.
- API
- Admin GraphQL API
- Operation
- metafieldDefinitionCreate
- Replaces (REST)
- None; definitions are GraphQL only
- API version
- 2026-10
- Last checked
In short
To create a metafield definition, call metafieldDefinitionCreate with name, namespace, key, ownerType and type, plus optional validations, access and pin. The definition gives the metafield a fixed type, an editor in the Shopify admin and rules such as a list of allowed values. Set access.storefront to PUBLIC_READ when a headless storefront needs to read it through the Storefront API.
How to use it
- Pick the owner type (PRODUCT here), a namespace and key, and one of Shopify’s metafield types.
- Add validations if you need them, for example choices for a fixed list of values. Validation values are strings, so a list is a JSON array in a string.
- Set access.storefront to PUBLIC_READ if a headless storefront reads the value, and pin: true to show it on the product page in the admin.
- Send CreateFabricDefinition and check userErrors; TAKEN means a definition with that namespace and key already exists.
Code
metafield-definition-create.graphqlmutation CreateFabricDefinition($definition: MetafieldDefinitionInput!) {
metafieldDefinitionCreate(definition: $definition) {
createdDefinition {
id
namespace
key
name
ownerType
type {
name
}
validations {
name
value
}
access {
storefront
}
}
userErrors {
code
field
message
}
}
}
metafield-definition-create.variables.json{
"definition": {
"name": "Fabric",
"namespace": "custom",
"key": "fabric",
"description": "Main fabric, shown on the product page and used as a filter.",
"ownerType": "PRODUCT",
"type": "single_line_text_field",
"validations": [
{
"name": "choices",
"value": "[\"Cotton\",\"Linen\",\"Wool\"]"
}
],
"access": {
"storefront": "PUBLIC_READ"
},
"pin": true
}
}
metafield-definition-create.response.json{
"data": {
"metafieldDefinitionCreate": {
"createdDefinition": {
"id": "gid://shopify/MetafieldDefinition/1234567890",
"namespace": "custom",
"key": "fabric",
"name": "Fabric",
"ownerType": "PRODUCT",
"type": {
"name": "single_line_text_field"
},
"validations": [
{
"name": "choices",
"value": "[\"Cotton\",\"Linen\",\"Wool\"]"
}
],
"access": {
"storefront": "PUBLIC_READ"
}
},
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- Existing metafields with the same owner type, namespace and key are checked against the new definition. Valid ones take its type; invalid ones keep their value but must match the definition the next time they’re saved.
- Leaving out namespace uses your app’s reserved namespace. Definitions under it are owned by your app.
- A definition can’t change its type later; create a new key if the type was wrong.
- The number of pinned definitions per owner type is limited; PINNED_LIMIT_REACHED in userErrors means you hit it.
Questions
- What is the difference between a metafield and a metafield definition?
- A metafield is a value on one resource. A definition describes the namespace and key for all resources of a type: its type, validation, admin editor and API access.
- Why can’t I read my metafield with the Storefront API?
- Its definition needs storefront access set to PUBLIC_READ. With NONE, the Storefront API can’t read the value.
- Can I restrict a metafield to a list of values?
- Yes. Add a choices validation with a JSON array of allowed values; the admin then shows a dropdown and the API rejects other values.
Shopify documentation
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
