---
title: Metaobject
description: Subscribe to field-level changes on the Metaobject GraphQL Admin API object.
api_version: 2026-10
source_url:
  html: 'https://shopify.dev/docs/api/events/latest/metaobject'
  md: 'https://shopify.dev/docs/api/events/latest/metaobject.md'
api_name: events
---

# Metaobject

**Requires `read_metaobjects` access scope.:**

Supported [actions](https://shopify.dev/docs/apps/build/events/subscribe#actions): `create`, `update`, `delete`

Subscribe to field-level changes on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject) GraphQL Admin API object.

Each [topic](https://shopify.dev/docs/api/events/latest#configuration) corresponds to a commerce resource that can exist independently within its domain. Child entities that depend on a parent within the same domain don't have their own topic. Instead, changes to child entities trigger a delivery on the parent topic. Calculated fields, derived fields, auto-updated timestamps, and cross-domain fields aren't available as triggers.

## shopify.app.toml

```toml
[events]
api_version = "2026-10"


[[events.subscription]]
handle = "my_metaobject_event"


topic = "Metaobject"
actions = ["update"]
triggers = ["metaobject(type: 'lookbook').displayName"]


uri = "https://your-app.com/events"


query = """
query metaobject_event_payload($metaobjectId: ID!) {
  metaobject(id: $metaobjectId) {
    id
    handle
    displayName
  }
}
"""
```

***

## Supported triggers

Field-level [triggers](https://shopify.dev/docs/api/events/latest#configuration) for `Metaobject` subscriptions.

All triggers require the `read_metaobjects` access scope. Those triggers that require additional scopes are documented where relevant. Deprecated triggers are listed last.

Subscriptions can include multiple triggers. Use the `shopify-webhook-id` header for deduplication when handling duplicate deliveries.

Custom queries aren't limited to [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject). They can query the full GraphQL Admin API.

### metaobject(type: String!)​.\*[](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject)

Fires when events involve the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject) object.

The `"create"` and `"delete"` actions are only relevant within the context of this parent topic. Use `fields_changed` to follow or replicate impacted data after a delete event. Define a custom query to retrieve specific fields from create events.

`metaobject(type: String!).*` is a parent trigger. Subscribing with the `"update"` action receives events for all supported triggers under `metaobject(type: String!)`, including nested triggers. Use a more specific trigger to limit events to the fields you need.

**Variables:** `metaobjectId`, `metaobjectType`

### metaobject(type: String!)​.displayName[](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.displayName)

Fires when the [`displayName`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.displayName) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `displayName` field represents the preferred display name field value of the metaobject.

**Variables:** `metaobjectId`, `metaobjectType`

### metaobject(type: String!)​.field(key: String!)​.\*[](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.field)

Fires when the [`field`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.field) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject) object changes.

`metaobject(type: String!).field(key: String!).*` is a parent trigger. Subscribing with the `"update"` action receives events for all supported triggers under `metaobject(type: String!).field(key: String!)`, including nested triggers. Use a more specific trigger to limit events to the fields you need.

Include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

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

**Variables:** `fieldKey`, `metaobjectId`, `metaobjectType`

### metaobject(type: String!)​.field(key: String!)​.value[](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/MetaobjectField#field-MetaobjectField.fields.value)

Fires when the [`value`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/MetaobjectField#field-MetaobjectField.fields.value) field on the [`MetaobjectField`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/MetaobjectField) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `value` field represents the assigned field value, always stored as a string regardless of the field type.

**Variables:** `fieldKey`, `metaobjectId`, `metaobjectType`

### metaobject(type: String!)​.handle[](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.handle)

Fires when the [`handle`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject#field-Metaobject.fields.handle) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Metaobject) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

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

**Variables:** `metaobjectId`, `metaobjectType`

### Examples

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "2026-10"

  [[events.subscription]]
  handle = "metaobject-event"

  topic = "Metaobject"
  actions = ["create","update","delete"]
  triggers = ["metaobject(type: 'lookbook').*"]

  uri = "https://your-app.com/events"

  query = """
  query metaobject_details($metaobjectId: ID!) {
    metaobject(id: $metaobjectId) {
      id
      handle
      displayName
    }
  }
  """
  ```

  ##### Payload (added)

  ```json
  {
    "topic": "Metaobject",
    "action": "create",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": {
      "added": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook']"
      ],
      "updated": [],
      "removed": []
    },
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Payload (updated)

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].displayName"
      ],
      "removed": []
    },
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Payload (removed)

  ```json
  {
    "topic": "Metaobject",
    "action": "delete",
    "handle": "metaobject-event",
    "data": {
      "metaobject": null
    },
    "fields_changed": {
      "added": [],
      "updated": [],
      "removed": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook']"
      ]
    },
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update # or create, delete
  shopify-api-version: 2026-10
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Metaobject
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "2026-10"

  [[events.subscription]]
  handle = "metaobject-event"

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: 'lookbook').displayName"]

  uri = "https://your-app.com/events"

  query = """
  query metaobject_event_payload($metaobjectId: ID!) {
    metaobject(id: $metaobjectId) {
      id
      handle
      displayName
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].displayName"
      ],
      "removed": []
    },
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: 2026-10
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Metaobject
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "2026-10"

  [[events.subscription]]
  handle = "metaobject-event"

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: 'lookbook').field(key: 'season').*"]

  uri = "https://your-app.com/events"

  query = """
  query metaobject_event_payload($metaobjectId: ID!, $fieldKey: String!) {
    metaobject(id: $metaobjectId) {
      id
      handle
      displayName
      field(key: $fieldKey) {
        __typename
      }
    }
  }
  """
  ```

  ##### Payload (added)

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer",
        "field": {
          "__typename": "MetaobjectField"
        }
      }
    },
    "fields_changed": {
      "added": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].field[key: 'season']"
      ],
      "updated": [],
      "removed": []
    },
    "query_variables": {
      "fieldKey": "season",
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Payload (removed)

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer",
        "field": {
          "__typename": "MetaobjectField"
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [],
      "removed": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].field[key: 'season']"
      ]
    },
    "query_variables": {
      "fieldKey": "season",
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: 2026-10
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Metaobject
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "2026-10"

  [[events.subscription]]
  handle = "metaobject-event"

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: 'lookbook').field(key: 'season').value"]

  uri = "https://your-app.com/events"

  query = """
  query metaobject_event_payload($metaobjectId: ID!, $fieldKey: String!) {
    metaobject(id: $metaobjectId) {
      id
      handle
      displayName
      field(key: $fieldKey) {
        value
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer",
        "field": {
          "value": "…"
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].field[key: 'season'].value"
      ],
      "removed": []
    },
    "query_variables": {
      "fieldKey": "season",
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: 2026-10
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Metaobject
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "2026-10"

  [[events.subscription]]
  handle = "metaobject-event"

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: 'lookbook').handle"]

  uri = "https://your-app.com/events"

  query = """
  query metaobject_event_payload($metaobjectId: ID!) {
    metaobject(id: $metaobjectId) {
      id
      handle
      displayName
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/7817395005142",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "metaobject[id: 'gid://shopify/Metaobject/7817395005142', type: 'lookbook'].handle"
      ],
      "removed": []
    },
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/7817395005142",
      "metaobjectType": "lookbook"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: 2026-10
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Metaobject
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

***