Skip to main content

Manage metaobjects

Metaobjects enable app users and app developers to define custom objects in Shopify. This guide shows you how to get started with creating and managing metaobjects and metaobject definitions using the GraphQL Admin API.


In this tutorial, you'll learn how to do the following tasks:

  • Define metaobjects
  • Create metaobject entries

  • Your app can make authenticated requests to the GraphQL Admin API.
  • You're using API version 2023-01 or higher.

You want your app to offer a way for users to create highlights for products they're creating. Users might want to showcase the quality of their goods or interesting facts about the product.


Anchor to Step 1: Define a product highlight metaobjectStep 1: Define a product highlight metaobject

Before users can start creating highlights, your app will need to tell Shopify what a product highlight is. Shopify doesn't have a product highlight resource, so you need to define one using the metaobjectDefinitionCreate mutation:

Note

The following example uses $app:product_highlights as its reserved type. Refer to ownership to learn more about reserved types and prefixes.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metaobjectDefinitionCreate(definition: {
type: "$app:product_highlight",
access: {
admin: MERCHANT_READ_WRITE,
storefront: PUBLIC_READ
},
capabilities: {
publishable: {
enabled: true
}
},
fieldDefinitions: [
{ key: "title", name: "Highlight Title", type: "single_line_text_field" },
{ key: "description", name: "Description", type: "multi_line_text_field" },
{ key: "creative", name: "Creative", type: "file_reference" }
]
}) {
metaobjectDefinition {
id
type
fieldDefinitions {
key
name
type {
name
}
}
}
}
}

JSON response

{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/1",
"type": "app--12345--product_highlight",
"fieldDefinitions": [
{
"key": "title",
"name": "Highlight Title",
"type": { "name": "single_line_text_field" }
},
{
"key": "description",
"name": "Description",
"type": { "name": "multi_line_text_field" }
},
{
"key": "creative",
"name": "Creative",
"type": { "name": "file_reference" }
}
]
}
}
}
}

Anchor to Step 2: Create a product highlight metaobject entryStep 2: Create a product highlight metaobject entry

After defining what a product highlight is, you can create entries or instances of your product highlights using the metaobjectCreate mutation:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation {
metaobjectCreate(metaobject: {
type: "$app:product_highlight",
fields: [
{
key: "title",
value: "100% Reusable Plastics"
},
{
key: "description",
value: "Rest easy - our glasses are made from 100% reusable materials"
},
{
key: "creative",
value: "gid://shopify/MediaImage/1"
}
]
}) {
metaobject {
id
type
title: field(key: "title") { value }
description: field(key: "description") { value },
creative: field(key: "creative") { value }
}
}
}

JSON response

{
"data": {
"metaobjectCreate": {
"metaobject": {
"id": "gid://shopify/Metaobject/1",
"type": "app--12345--product_highlight",
"title": {
"value": "100% Reusable Plastics"
},
"description": {
"value": "Rest easy - our glasses are made from 100% reusable materials"
},
"creative": {
"value": "gid://shopify/MediaImage/1"
}
}
}
}
}

Anchor to Step 3: Retrieve your product highlightsStep 3: Retrieve your product highlights

With your product highlight entry now created, you can read it back from the API using the metaobjects paginated query to retrieve all of your highlights:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query {
metaobjects(type: "$app:product_highlight", first: 10) {
nodes {
handle
type
title: field(key: "title") { value }
description: field(key: "description") { value },
creative: field(key: "creative") { value }
}
}
}

JSON response

{
"data": {
"metaobjects": {
"nodes": [{
"handle": "100-reusable-plastics",
"type": "app--12345--product_highlight",
"title": {
"value": "100% Reusable Plastics"
},
"description": {
"value": "Rest easy - our glasses are made from 100% reusable materials"
},
"creative": {
"value": "gid://shopify/MediaImage/1"
}
}]
}
}
}

You can also retrieve a single metaobject by its handle using the metaobjectByHandle query:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query {
metaobjectByHandle(handle: {
type: "$app:product_highlight",
handle: "app--3949353--product-highlight-gbcnbvsg"
}) {
displayName
title: field(key: "title") { value }
description: field(key: "description") { value },
creative: field(key: "creative") { value }
}
}

JSON response

{
"data": {
"metaobject": {
"displayName": "100% Reusable Plastics",
"title": {
"value": "100% Reusable Plastics"
},
"description": {
"value": "Rest easy - our glasses are made from 100% reusable materials"
},
"creative": {
"value": "gid://shopify/MediaImage/1"
}
}
}
}


Was this page helpful?