Choose a version:

metaobjectUpdate

mutation

Requires write_metaobjects access scope.

Updates a Metaobject with new field values, handle, or capabilities. Metaobjects are custom data structures that extend Shopify's data model.

You can modify field values mapped to the metaobject's MetaobjectDefinition, update the handle for a unique identifier, and adjust capabilities like publishing status. When updating the handle, you can optionally create a redirect from the old handle to maintain existing references.

Anchor to Arguments

Arguments

Anchor to idid

•ID!

required

The ID of the metaobject to update.

Anchor to metaobjectmetaobject

•MetaobjectUpdateInput!

required

Specifies parameters to update on the metaobject.

Was this section helpful?

Anchor to MetaobjectUpdatePayload returnsMetaobjectUpdatePayload returns

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

Was this section helpful?

Examples

Update a metaobject

Description

To update an existing metaobject, you can use the `metaobjectUpdate` mutation with the `id` and `metaobject` arguments. The following example updates the `season` field to be `winter` for the `fall-2021` "LookBook" metaobject.

Query

mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
  metaobjectUpdate(id: $id, metaobject: $metaobject) {
    metaobject {
      handle
      season: field(key: "season") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "id": "gid://shopify/Metaobject/515107504",
  "metaobject": {
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) { metaobjectUpdate(id: $id, metaobject: $metaobject) { metaobject { handle season: field(key: \"season\") { value } } userErrors { field message code } } }",
 "variables": {
    "id": "gid://shopify/Metaobject/515107504",
    "metaobject": {
      "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
    metaobjectUpdate(id: $id, metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
    metaobjectUpdate(id: $id, metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Metaobject/515107504",
  "metaobject": {
    "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
      metaobjectUpdate(id: $id, metaobject: $metaobject) {
        metaobject {
          handle
          season: field(key: "season") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
  metaobjectUpdate(id: $id, metaobject: $metaobject) {
    metaobject {
      handle
      season: field(key: "season") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Metaobject/515107504",
  "metaobject": {
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
        metaobjectUpdate(id: $id, metaobject: $metaobject) {
          metaobject {
            handle
            season: field(key: "season") {
              value
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "metaobjectUpdate": {
    "metaobject": {
      "handle": "fall-2021",
      "season": {
        "value": "winter"
      }
    },
    "userErrors": []
  }
}

metaobjectUpdate reference

Examples

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

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

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

const response = await admin.graphql(

`#graphql

mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {

metaobjectUpdate(id: $id, metaobject: $metaobject) {

metaobject {

handle

season: field(key: "season") {

value

}

userErrors {

field

message

code

}

}`,

{

variables: {

"id": "gid://shopify/Metaobject/515107504",

"metaobject": {

"fields": [

{

"key": "season",

"value": "winter"

}

]

}

);

const json = await response.json();

return json.data;

}

GQL

mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
  metaobjectUpdate(id: $id, 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/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) { metaobjectUpdate(id: $id, metaobject: $metaobject) { metaobject { handle season: field(key: \"season\") { value } } userErrors { field message code } } }",
 "variables": {
    "id": "gid://shopify/Metaobject/515107504",
    "metaobject": {
      "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
    metaobjectUpdate(id: $id, metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
      metaobjectUpdate(id: $id, metaobject: $metaobject) {
        metaobject {
          handle
          season: field(key: "season") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "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 UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
    metaobjectUpdate(id: $id, metaobject: $metaobject) {
      metaobject {
        handle
        season: field(key: "season") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Metaobject/515107504",
  "metaobject": {
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
  metaobjectUpdate(id: $id, metaobject: $metaobject) {
    metaobject {
      handle
      season: field(key: "season") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Metaobject/515107504",
  "metaobject": {
    "fields": [
      {
        "key": "season",
        "value": "winter"
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation UpdateMetaobject($id: ID!, $metaobject: MetaobjectUpdateInput!) {
        metaobjectUpdate(id: $id, metaobject: $metaobject) {
          metaobject {
            handle
            season: field(key: "season") {
              value
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Metaobject/515107504",
        "metaobject": {
            "fields": [
                {
                    "key": "season",
                    "value": "winter"
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"id": "gid://shopify/Metaobject/515107504",

"metaobject": {

"fields": [

{

"key": "season",

"value": "winter"

}

]

}

Response

JSON

{

"metaobjectUpdate": {

"metaobject": {

"handle": "fall-2021",

"season": {

"value": "winter"

}

"userErrors": []

}