Skip to main content
Anchor to Metaobject

Metaobject

object

Requires read_metaobjects access scope.

An instance of custom structured data defined by a MetaobjectDefinition. Metaobjects store reusable data that extends beyond Shopify's standard resources, such as product highlights, size charts, or custom content sections.

Each metaobject includes fields that match the field types and validation rules specified in its definition, which also determines the metaobject's capabilities, such as storefront visibility, publishing and translation support. Metafields can reference metaobjects to connect custom data with Product objects, Collection objects, and other Shopify resources.

Anchor to FieldsFields

Anchor to capabilitiescapabilities
•MetaobjectCapabilityData!
non-null

Metaobject capabilities for this Metaobject.

Anchor to createdAtcreatedAt
•DateTime!
non-null

When the object was created.

Anchor to createdBycreatedBy
•App!
non-null

The app used to create the object.

Anchor to createdByAppcreatedByApp
•App!
non-null

The app used to create the object.

Anchor to createdByStaffcreatedByStaff
•StaffMember

The staff member who created the metaobject.

Anchor to definitiondefinition
•MetaobjectDefinition!
non-null

The MetaobjectDefinition that models this object type.

Anchor to displayNamedisplayName
•String!
non-null

The preferred display name field value of the metaobject.

Anchor to fieldfield
•MetaobjectField

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

Arguments

Anchor to keykey
•String!
required

The metaobject key to access.

Anchor to fieldsfields
•[MetaobjectField!]!
non-null

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

Anchor to handlehandle
•String!
non-null

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

Anchor to idid
•ID!
non-null

A globally-unique ID.

Anchor to referencedByreferencedBy
•MetafieldRelationConnection!
non-null

List of back references metafields that belong to the resource.

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to thumbnailFieldthumbnailField
•MetaobjectField

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

Anchor to typetype
•String!
non-null

The type of the metaobject.

Anchor to updatedAtupdatedAt
•DateTime!
non-null

When the object was last updated.

Deprecated fields

Anchor to appapp
•App!
non-nullDeprecated
Anchor to staffMemberstaffMember
•StaffMember
Deprecated
Was this section helpful?

Anchor to QueriesQueries

Anchor to metaobjectmetaobject
•query

Retrieves a single Metaobject by its global ID. Metaobjects store custom structured data based on defined schemas. The returned metaobject includes its fields with values, display name, handle, and associated metadata like update timestamps and capabilities.

Arguments

Anchor to idid
•ID!
required

The ID of the metaobject to return.

Anchor to metaobjectByHandlemetaobjectByHandle
•query

Retrieves a Metaobject by its handle and type. Handles are unique identifiers within a metaobject type.

Arguments

Anchor to handlehandle
•MetaobjectHandleInput!
required

The identifier of the metaobject to return.

Anchor to metaobjectsmetaobjects
•query

Returns a paginated list of Metaobject entries for a specific type. Metaobjects are custom data structures that extend Shopify's data model with merchant or app-specific data types.

Filter results using the query parameter with a search syntax for metaobject fields. Use fields.{key}:{value} to filter by field values, supporting any field previously marked as filterable. The sortKey parameter accepts id, type, updated_at, or display_name to control result ordering.

Learn more about querying metaobjects by field value.

Arguments

Anchor to typetype
•String!
required

The type of the metaobjects to query.

Anchor to sortKeysortKey
•String

The key of a field to sort with. Supports "id", "type", "updated_at", and "display_name".

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to queryquery
•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to display_name
•string
Anchor to fields.{key}
•mixed

Filters metaobject entries by field value. Format: fields.{key}:{value}. Only fields marked as filterable in the metaobject definition can be used. Learn more about querying metaobjects by field value.

Example:

  • fields.color:blue
  • fields.on_sale:true
Anchor to handle
•string
Anchor to id
•id

Filter by id range.

Example:

  • id:1234
  • id:>=1234
  • id:<=1234
Anchor to updated_at
•time
Was this section helpful?

Anchor to MutationsMutations

Anchor to metaobjectCreatemetaobjectCreate
•mutation

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.

Arguments

Anchor to metaobjectmetaobject
•MetaobjectCreateInput!
required

The parameters for the metaobject to create.

Anchor to metaobjectsCreatemetaobjectsCreate
•mutation

Creates up to 25 metaobjects of the same type.

Arguments

Anchor to inputinput
•MetaobjectsCreateInput!
required

The parameters for the metaobjects to create.

Anchor to metaobjectUpdatemetaobjectUpdate
•mutation

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.

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.

Anchor to metaobjectUpsertmetaobjectUpsert
•mutation

Creates or updates a Metaobject based on its handle. If a metaobject with the specified handle exists, the mutation updates it with the provided field values. If no matching metaobject exists, the mutation creates a new one.

The handle serves as a unique identifier within a metaobject type. Field values map to the MetaobjectDefinition's field keys and overwrite existing values during updates.

Arguments

Anchor to handlehandle
•MetaobjectHandleInput!
required

The identifier of the metaobject to upsert.

Anchor to metaobjectmetaobject
•MetaobjectUpsertInput!
required

The parameters to upsert the metaobject.

Was this section helpful?

Anchor to InterfacesInterfaces

Anchor to NodeNode
•interface
Was this section helpful?