Create a metaobject definition
Description
A metaobject definition provides the blueprint for a metaobject by defining its type and possible
fields. You can create a metaobject definition using the `metaobjectDefinitionCreate` mutation.
The following example shows how to add a metaobject definition called "Color swatch" that has a
single line text field called "Hex" which stores the color's hex code.
Query
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
Variables
{
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
}
cURL
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type fieldDefinitions { name key } } userErrors { field message code } } }",
"variables": {
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
}
}'
React Router
import { authenticate } from "../shopify.server";
export const loader = async ({request}) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
{
variables: {
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
},
},
);
const json = await response.json();
return json.data;
}
Ruby
session = ShopifyAPI::Auth::Session.new(
shop: "your-development-store.myshopify.com",
access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
session: session
)
query = <<~QUERY
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
QUERY
variables = {
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
}
response = client.query(query: query, variables: variables)
Node.js
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: {
"query": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
"variables": {
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
},
},
});
Shopify CLI
shopify app execute \
--query \
'mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}' \
--variables \
'{
"definition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex",
"type": "single_line_text_field",
"validations": [
{
"name": "regex",
"value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
}
]
}
]
}
}'
Response
{
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"name": "Color swatch",
"type": "color-swatch",
"fieldDefinitions": [
{
"name": "Hex",
"key": "hex"
}
]
},
"userErrors": []
}
}
Create a metaobject definition with custom access controls
Description
You can create a metaobject definition with custom access controls by using the
`metaobjectDefinitionCreate` mutation along with the `access` input.
The following example shows how to create a metaobject definition called "FAQ" that has two fields:
"Question" and "Answer". The FAQ metaobject is defined using the `MERCHANT_READ_WRITE` admin access
setting and `PUBLIC_READ` storefront access setting to make it read/writable within the merchant's
admin and also be readable by the storefront. Note: By using the `$app:` prefix in the `type` field,
the metaobject definition will be reserved for use by the app that created it and prevents other apps
from modifying the definition.
Query
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
access {
admin
storefront
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
Variables
{
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
}
cURL
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type access { admin storefront } fieldDefinitions { name key } } userErrors { field message code } } }",
"variables": {
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
}
}'
React Router
import { authenticate } from "../shopify.server";
export const loader = async ({request}) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
access {
admin
storefront
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
{
variables: {
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
},
},
);
const json = await response.json();
return json.data;
}
Ruby
session = ShopifyAPI::Auth::Session.new(
shop: "your-development-store.myshopify.com",
access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
session: session
)
query = <<~QUERY
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
access {
admin
storefront
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
QUERY
variables = {
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
}
response = client.query(query: query, variables: variables)
Node.js
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: {
"query": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
access {
admin
storefront
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
"variables": {
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
},
},
});
Shopify CLI
shopify app execute \
--query \
'mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
access {
admin
storefront
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}' \
--variables \
'{
"definition": {
"name": "FAQ",
"type": "$app:faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Answer",
"key": "answer",
"type": "multi_line_text_field",
"validations": [
{
"name": "max",
"value": "250"
}
]
}
]
}
}'
Response
{
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"name": "FAQ",
"type": "app--1830279--faq",
"access": {
"admin": "MERCHANT_READ_WRITE",
"storefront": "PUBLIC_READ"
},
"fieldDefinitions": [
{
"name": "Question",
"key": "question"
},
{
"name": "Answer",
"key": "answer"
}
]
},
"userErrors": []
}
}
Create a metaobject definition with the publishable capability enabled
Description
Using the `capabilities` input, you can enable the publishable capability within your
`metaobjectDefinitionCreate` mutation.
The following example shows how to create a metaobject definition called "Custom Page"
that has a "title" and "author" field. Enabling `publishable` provides metaobjects created with this
definition a `status` field that can be used to stage metaobjects using `DRAFT` or `ACTIVE`.
Query
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
Variables
{
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
}
cURL
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type capabilities { publishable { enabled } } fieldDefinitions { name key } } userErrors { field message code } } }",
"variables": {
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
}
}'
React Router
import { authenticate } from "../shopify.server";
export const loader = async ({request}) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
{
variables: {
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
},
},
);
const json = await response.json();
return json.data;
}
Ruby
session = ShopifyAPI::Auth::Session.new(
shop: "your-development-store.myshopify.com",
access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
session: session
)
query = <<~QUERY
mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}
QUERY
variables = {
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
}
response = client.query(query: query, variables: variables)
Node.js
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: {
"query": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}`,
"variables": {
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
},
},
});
Shopify CLI
shopify app execute \
--query \
'mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
name
type
capabilities {
publishable {
enabled
}
}
fieldDefinitions {
name
key
}
}
userErrors {
field
message
code
}
}
}' \
--variables \
'{
"definition": {
"name": "Custom Page",
"type": "$app:custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "100"
}
]
},
{
"name": "Author",
"key": "author",
"type": "single_line_text_field",
"validations": [
{
"name": "max",
"value": "32"
}
]
}
]
}
}'
Response
{
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"name": "Custom Page",
"type": "app--1830279--custom-page",
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{
"name": "Title",
"key": "title"
},
{
"name": "Author",
"key": "author"
}
]
},
"userErrors": []
}
}