---
title: metaobject - Storefront API
description: |-
  Retrieves a single [`Metaobject`](/docs/api/storefront/2026-07/objects/Metaobject)
  by either its [`global ID`](/docs/api/storefront/2026-07/queries/metaobject#arguments-id) or its [`handle`](/docs/api/storefront/2026-07/queries/metaobject#arguments-handle).

  > Note:
  > When using the handle, you must also provide the metaobject type because handles are only unique within a type.
api_version: 2026-07
source_url:
  html: https://shopify.dev/docs/api/storefront/latest/queries/Metaobject
  md: https://shopify.dev/docs/api/storefront/latest/queries/Metaobject.md
---

# metaobject

query

Requires `unauthenticated_read_metaobjects` access scope.

Retrieves a single [`Metaobject`](https://shopify.dev/docs/api/storefront/2026-07/objects/Metaobject) by either its [`global ID`](https://shopify.dev/docs/api/storefront/2026-07/queries/metaobject#arguments-id) or its [`handle`](https://shopify.dev/docs/api/storefront/2026-07/queries/metaobject#arguments-handle).

***

**Note:** When using the handle, you must also provide the metaobject type because handles are only unique within a type.

***

## Arguments

* handle

  [Metaobject​Handle​Input](https://shopify.dev/docs/api/storefront/latest/input-objects/MetaobjectHandleInput)

  The handle and type of the metaobject.

* id

  [ID](https://shopify.dev/docs/api/storefront/latest/scalars/ID)

  The ID of the metaobject.

***

## Possible returns

* Metaobject

  [Metaobject](https://shopify.dev/docs/api/storefront/latest/objects/Metaobject)

  An instance of [custom structured data](https://shopify.dev/docs/apps/build/metaobjects) defined by a metaobject definition. Metaobjects store reusable content that extends beyond standard Shopify resources, such as size charts, author profiles, or custom content sections.

  Each metaobject contains fields that match the types and validation rules specified in its definition. [`Metafield`](https://shopify.dev/docs/api/storefront/2026-07/objects/Metafield) references can point to metaobjects, connecting custom data with products, collections, and other resources. If the definition has the `renderable` capability, then the [`seo`](https://shopify.dev/docs/api/storefront/2026-07/objects/Metaobject#field-Metaobject.fields.seo) field provides SEO metadata. If it has the `online_store` capability, then the [`onlineStoreUrl`](https://shopify.dev/docs/api/storefront/2026-07/objects/Metaobject#field-Metaobject.fields.onlineStoreUrl) field returns the public URL.

  * field

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

    Token access required

    Accesses a field of the object by key.

    * key

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

      required

      ### Arguments

      The key of the field.

    ***

  * fields

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

    non-null Token access required

    All object fields with defined values. Omitted object keys can be assumed null, and no guarantees are made about field order.

  * handle

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

    non-null Token access required

    The unique handle of the metaobject. Useful as a custom ID.

  * id

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

    non-null Token access required

    A globally-unique ID.

  * online​Store​Url

    [URL](https://shopify.dev/docs/api/storefront/latest/scalars/URL)

    Token access required

    The URL used for viewing the metaobject on the shop's Online Store. Returns `null` if the metaobject definition doesn't have the `online_store` capability.

  * seo

    [Metaobject​SEO](https://shopify.dev/docs/api/storefront/latest/objects/MetaobjectSEO)

    Token access required

    The metaobject's SEO information. Returns `null` if the metaobject definition doesn't have the `renderable` capability.

  * type

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

    non-null Token access required

    The type of the metaobject.

  * updated​At

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

    non-null Token access required

    The date and time when the metaobject was last updated.

***

## Examples

* ### metaobject reference