Choose a version:

metaobjectByHandle

query

Requires read_metaobjects access scope.

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

Anchor to Arguments

Arguments

Anchor to handlehandle

•MetaobjectHandleInput!

required

The identifier of the metaobject to return.

Show input fields

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to MetaobjectMetaobject

•Metaobject

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.

Show fields

Anchor to capabilitiescapabilities

•MetaobjectCapabilityData!

non-null

Metaobject capabilities for this Metaobject.

Show fields

Anchor to createdAtcreatedAt

•DateTime!

non-null

When the object was created.

Anchor to createdBycreatedBy

•App!

non-null

The app used to create the object.

Show fields

Anchor to createdByAppcreatedByApp

•App!

non-null

The app used to create the object.

Show fields

Anchor to createdByStaffcreatedByStaff

•StaffMember

The staff member who created the metaobject.

Show fields

Anchor to definitiondefinition

•MetaobjectDefinition!

non-null

The MetaobjectDefinition that models this object type.

Show fields

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.

Show fields

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.

Show fields

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.

Show fields

Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to lastlast •Int: The last n elements from the paginated list.
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.

Show fields

Anchor to typetype

•String!

non-null

The type of the metaobject.

Anchor to updatedAtupdatedAt

•DateTime!

non-null

When the object was last updated.

Anchor to valuesvalues

•JSON!

non-null

The values of the metaobject.

Anchor to appapp

•App!

non-nullDeprecated

Show fields

Anchor to staffMemberstaffMember

•StaffMember

Deprecated

Show fields

Was this section helpful?

Examples

Fetch a metaobject by handle

Description

Retrieves a metaobject by its type and handle.

Query

query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    type
    displayName
    values
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetaobjectByHandle { metaobjectByHandle(handle: {type: \"$app:author\", handle: \"jane-austen\"}) { id handle type displayName values } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }`,
  );
  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
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }`,
});

Shopify CLI

shopify app execute \
--query \
'query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    type
    displayName
    values
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query MetaobjectByHandle {
        metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
          id
          handle
          type
          displayName
          values
        }
      }
    `,
  }),
});

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

Response

{
  "metaobjectByHandle": {
    "id": "gid://shopify/Metaobject/971662561",
    "handle": "jane-austen",
    "type": "app--2459039--author",
    "displayName": "Jane Austen",
    "values": {
      "first_published": "1811-01-01",
      "full_name": "Jane Austen"
    }
  }
}

Fetch metaobject with publish status

Description

Retrieves a metaobject with its capabilities. The capabilities.publishable field shows whether the entry's status is DRAFT or ACTIVE.

Query

query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    displayName
    capabilities {
      publishable {
        status
      }
    }
    values
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetaobjectByHandle { metaobjectByHandle(handle: {type: \"$app:author\", handle: \"jane-austen\"}) { id handle displayName capabilities { publishable { status } } values } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      displayName
      capabilities {
        publishable {
          status
        }
      }
      values
    }
  }`,
  );
  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
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      displayName
      capabilities {
        publishable {
          status
        }
      }
      values
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      displayName
      capabilities {
        publishable {
          status
        }
      }
      values
    }
  }`,
});

Shopify CLI

shopify app execute \
--query \
'query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    displayName
    capabilities {
      publishable {
        status
      }
    }
    values
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query MetaobjectByHandle {
        metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
          id
          handle
          displayName
          capabilities {
            publishable {
              status
            }
          }
          values
        }
      }
    `,
  }),
});

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

Response

{
  "metaobjectByHandle": {
    "id": "gid://shopify/Metaobject/971662562",
    "handle": "jane-austen",
    "displayName": "Jane Austen",
    "capabilities": {
      "publishable": {
        "status": "ACTIVE"
      }
    },
    "values": {
      "first_published": "1811-01-01",
      "full_name": "Jane Austen"
    }
  }
}

Examples

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

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

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

const response = await admin.graphql(

`#graphql

query MetaobjectByHandle {

metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {

handle

type

displayName

values

}

}`,

);

const json = await response.json();

return json.data;

}

GQL

query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    type
    displayName
    values
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetaobjectByHandle { metaobjectByHandle(handle: {type: \"$app:author\", handle: \"jane-austen\"}) { id handle type displayName values } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }`,
});

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
  query MetaobjectByHandle {
    metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
      id
      handle
      type
      displayName
      values
    }
  }
QUERY

response = client.query(query: query)

Shopify CLI

shopify app execute \
--query \
'query MetaobjectByHandle {
  metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
    id
    handle
    type
    displayName
    values
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query MetaobjectByHandle {
        metaobjectByHandle(handle: {type: "$app:author", handle: "jane-austen"}) {
          id
          handle
          type
          displayName
          values
        }
      }
    `,
  }),
});

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

Response

JSON

{

"metaobjectByHandle": {

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

"handle": "jane-austen",

"type": "app--2459039--author",

"displayName": "Jane Austen",

"values": {

"first_published": "1811-01-01",

"full_name": "Jane Austen"

}