---
title: Manage metaobjects
description: >-
  Learn how to create and read metaobject definitions and entries using the
  GraphQL Admin API.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects
  md: >-
    https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md
---

ExpandOn this page

* [What you'll learn](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#requirements)
* [Scenario](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#scenario)
* [Step 1: Define a product highlight metaobject](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-1-define-a-product-highlight-metaobject)
* [Step 2: Create a product highlight metaobject entry](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-2-create-a-product-highlight-metaobject-entry)
* [Step 3: Retrieve your product highlights](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-3-retrieve-your-product-highlights)
* [Next steps](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#next-steps)

# 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.

***

## What you'll learn

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

* Define metaobjects
* Create metaobject entries

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
* You're using API version 2023-01 or higher.

***

## Scenario

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.

***

## Step 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:

Note

The following example uses `$app:product_highlight` as its reserved type. Refer to [ownership](https://shopify.dev/docs/apps/build/custom-data/ownership) to learn more about reserved types and prefixes.

## shopify.app.toml

```toml
[metaobjects.app.product_highlight]
name = "Product Highlight"
access.admin = "merchant_read_write"
access.storefront = "public_read"
capabilities.publishable = true


[metaobjects.app.product_highlight.fields.title]
name = "Highlight Title"
type = "single_line_text_field"


[metaobjects.app.product_highlight.fields.description]
name = "Description"
type = "multi_line_text_field"


[metaobjects.app.product_highlight.fields.creative]
name = "Creative"
type = "file_reference"
```

```graphql
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
        }
      }
    }
  }
}
```

##### TOML

```
[metaobjects.app.product_highlight]
name = "Product Highlight"
access.admin = "merchant_read_write"
access.storefront = "public_read"
capabilities.publishable = true

[metaobjects.app.product_highlight.fields.title]
name = "Highlight Title"
type = "single_line_text_field"

[metaobjects.app.product_highlight.fields.description]
name = "Description"
type = "multi_line_text_field"

[metaobjects.app.product_highlight.fields.creative]
name = "Creative"
type = "file_reference"
```

##### GraphQL

```
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
        }
      }
    }
  }
}
```

***

## Step 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metaobjectCreate) mutation:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
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

```json
{
  "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"
        }
      }
    }
  }
}
```

***

## Step 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

```graphql
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

```json
{
  "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

```graphql
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

```json
{
  "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"
      }
    }
  }
}
```

***

## Next steps

* Learn more about [access controls](https://shopify.dev/docs/apps/build/custom-data/permissions).
* Learn about [metaobject capabilities](https://shopify.dev/docs/apps/build/custom-data/metaobjects/use-metaobject-capabilities).
* Learn about [the limits](https://shopify.dev/docs/apps/build/custom-data/metaobjects/metaobject-limits) on how many metaobject definitions and entries can be created.

***

* [What you'll learn](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#requirements)
* [Scenario](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#scenario)
* [Step 1: Define a product highlight metaobject](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-1-define-a-product-highlight-metaobject)
* [Step 2: Create a product highlight metaobject entry](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-2-create-a-product-highlight-metaobject-entry)
* [Step 3: Retrieve your product highlights](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#step-3-retrieve-your-product-highlights)
* [Next steps](https://shopify.dev/docs/apps/build/custom-data/metaobjects/manage-metaobjects.md#next-steps)