Choose a version:

metaobjectCreate

mutation

Requires write_metaobjects access scope.

Creates a metaobject entry based on an existing MetaobjectDefinition. The type must match a definition that already exists in the shop.

Specify field values using key-value pairs that correspond to the field definitions. The mutation generates a unique handle automatically if you don't provide one. You can also configure capabilities like publishable status to control the metaobject's visibility across channels.

Learn more about managing metaobjects.

Anchor to Arguments

Arguments

Anchor to metaobjectmetaobject •MetaobjectCreateInput! required: The parameters for the metaobject to create.

Was this section helpful?

Anchor to MetaobjectCreatePayload returnsMetaobjectCreatePayload returns

Anchor to metaobjectmetaobject •Metaobject: The created metaobject.
Anchor to userErrorsuserErrors •[MetaobjectUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create a metaobject

Description

To create a metaobject, you can use the `metaobjectCreate` mutation along with the metaobject as an argument providing the type and fields you want to create. A `MetaobjectDefinition` with the specified type and fields must already exist. The following example creates a new "Lookbook" metaobject with the `winter-2023` handle and the season field set to `winter`.

Query

mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    metaobject {
      handle
      season: field(key: "season") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "metaobject": {
    "type": "lookbook",
    "handle": "winter-2023",
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) { metaobjectCreate(metaobject: $metaobject) { metaobject { handle season: field(key: \"season\") { value } } userErrors { field message code } } }",
 "variables": {
    "metaobject": {
      "type": "lookbook",
      "handle": "winter-2023",
      "fields": [
        {
          "key": "season",
          "value": "winter"
        }
      ]
    }
  }
}'

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 CreateMetaobject($metaobject: MetaobjectCreateInput!) {
    metaobjectCreate(metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "metaobject": {
            "type": "lookbook",
            "handle": "winter-2023",
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  },
  );
  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 CreateMetaobject($metaobject: MetaobjectCreateInput!) {
    metaobjectCreate(metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "metaobject": {
    "type": "lookbook",
    "handle": "winter-2023",
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {
      metaobjectCreate(metaobject: $metaobject) {
        metaobject {
          handle
          season: field(key: "season") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "metaobject": {
            "type": "lookbook",
            "handle": "winter-2023",
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  },
});

Response

{
  "metaobjectCreate": {
    "metaobject": {
      "handle": "winter-2023",
      "season": {
        "value": "winter"
      }
    },
    "userErrors": []
  }
}

metaobjectCreate reference

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {

metaobjectCreate(metaobject: $metaobject) {

metaobject {

handle

season: field(key: "season") {

value

}

userErrors {

field

message

code

}

}`,

{

variables: {

"metaobject": {

"type": "lookbook",

"handle": "winter-2023",

"fields": [

{

"key": "season",

"value": "winter"

}

]

}

);

const json = await response.json();

return json.data;

}

GQL

mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    metaobject {
      handle
      season: field(key: "season") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) { metaobjectCreate(metaobject: $metaobject) { metaobject { handle season: field(key: \"season\") { value } } userErrors { field message code } } }",
 "variables": {
    "metaobject": {
      "type": "lookbook",
      "handle": "winter-2023",
      "fields": [
        {
          "key": "season",
          "value": "winter"
        }
      ]
    }
  }
}'

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 CreateMetaobject($metaobject: MetaobjectCreateInput!) {
    metaobjectCreate(metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "metaobject": {
            "type": "lookbook",
            "handle": "winter-2023",
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetaobject($metaobject: MetaobjectCreateInput!) {
      metaobjectCreate(metaobject: $metaobject) {
        metaobject {
          handle
          season: field(key: "season") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "metaobject": {
            "type": "lookbook",
            "handle": "winter-2023",
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  },
});

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 CreateMetaobject($metaobject: MetaobjectCreateInput!) {
    metaobjectCreate(metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "metaobject": {
    "type": "lookbook",
    "handle": "winter-2023",
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"metaobject": {

"type": "lookbook",

"handle": "winter-2023",

"fields": [

{

"key": "season",

"value": "winter"

}

]

}

Response

JSON

{

"metaobjectCreate": {

"metaobject": {

"handle": "winter-2023",

"season": {

"value": "winter"

}

"userErrors": []

}