---
title: Metaobject - GraphQL Admin
description: Provides an object instance represented by a MetaobjectDefinition.
api_version: 2025-10
api_name: admin
type: object
api_type: graphql
source_url:
  html: https://shopify.dev/docs/api/admin-graphql/latest/objects/Metaobject
  md: https://shopify.dev/docs/api/admin-graphql/latest/objects/Metaobject.md
---

# Metaobject

object

Requires `read_metaobjects` access scope.

Provides an object instance represented by a MetaobjectDefinition.

## Fields

* capabilities

  [Metaobject​Capability​Data!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectCapabilityData)

  non-null

  Metaobject capabilities for this Metaobject.

* created​By

  [App!](https://shopify.dev/docs/api/admin-graphql/latest/objects/App)

  non-null

  The app used to create the object.

* created​By​App

  [App!](https://shopify.dev/docs/api/admin-graphql/latest/objects/App)

  non-null

  The app used to create the object.

* created​By​Staff

  [Staff​Member](https://shopify.dev/docs/api/admin-graphql/latest/objects/StaffMember)

  The staff member who created the metaobject.

* definition

  [Metaobject​Definition!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectDefinition)

  non-null

  The MetaobjectDefinition that models this object type.

* display​Name

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  non-null

  The preferred display name field value of the metaobject.

* field

  [Metaobject​Field](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectField)

  The field for an object key, or null if the key has no field definition.

* fields

  [\[Metaobject​Field!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectField)

  non-null

  All ordered fields of the metaobject with their definitions and values.

* handle

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  non-null

  The unique handle of the object, useful as a custom ID.

* id

  [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  non-null

  A globally-unique ID.

* referenced​By

  [Metafield​Relation​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldRelationConnection)

  non-null

  List of back references metafields that belong to the resource.

* thumbnail​Field

  [Metaobject​Field](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectField)

  The recommended field to visually represent this metaobject. May be a file reference or color field.

* type

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  non-null

  The type of the metaobject.

* updated​At

  [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime)

  non-null

  When the object was last updated.

* staff​Member

  [Staff​Member](https://shopify.dev/docs/api/admin-graphql/latest/objects/StaffMember)

  Deprecated

***

## Map

### Fields and connections with this object

* <->[MetaobjectConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetaobjectConnection#returns-nodes)
* {}[MetaobjectDefinition.metaobjects](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectDefinition#field-MetaobjectDefinition.fields.metaobjects)
* {}[MetaobjectEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetaobjectEdge#field-MetaobjectEdge.fields.node)

### Possible type in

* [Metafield​Reference](https://shopify.dev/docs/api/admin-graphql/latest/unions/MetafieldReference)
* [Metafield​Referencer](https://shopify.dev/docs/api/admin-graphql/latest/unions/MetafieldReferencer)

***

## Queries

* [metaobject](https://shopify.dev/docs/api/admin-graphql/latest/queries/metaobject)

  query

  Retrieves a metaobject by ID.

* [metaobject​By​Handle](https://shopify.dev/docs/api/admin-graphql/latest/queries/metaobjectByHandle)

  query

  Retrieves a metaobject by handle.

* [metaobjects](https://shopify.dev/docs/api/admin-graphql/latest/queries/metaobjects)

  query

  All metaobjects for the shop.

***

## \<?>Metaobject Queries

### Queried by

* \<?>[metaobject](https://shopify.dev/docs/api/admin-graphql/latest/queries/Metaobject)
* \<?>[metaobject​By​Handle](https://shopify.dev/docs/api/admin-graphql/latest/queries/Metaobject)
* \<?>[metaobjects](https://shopify.dev/docs/api/admin-graphql/latest/queries/MetaobjectConnection)

***

## Mutations

* [metaobject​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectCreate)

  mutation

  Creates a new metaobject.

* [metaobject​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectUpdate)

  mutation

  Updates an existing metaobject.

* [metaobject​Upsert](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectUpsert)

  mutation

  Retrieves a metaobject by handle, then updates it with the provided input values. If no matching metaobject is found, a new metaobject is created with the provided input values.

***

## <\~> Metaobject Mutations

### Mutated by

* <\~>[metaobject​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectCreate)
* <\~>[metaobject​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectUpdate)
* <\~>[metaobject​Upsert](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectUpsert)

***

## Interfaces

* [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)

  interface

***

## ||-Metaobject Implements

### Implements

* ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)