---
title: Metaobject
description: Subscribe to field-level changes on the Metaobject GraphQL Admin API object.
api_version: unstable
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.:**

Subscribe to field-level changes on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metaobject) GraphQL Admin API object. You can subscribe to create, delete, and update events, and to changes to specific fields.

Each [topic](https://shopify.dev/docs/api/events/latest#configuration) corresponds to a commerce resource, such as a metaobject, 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.

You can't use calculated fields, derived fields, auto-updated timestamps, or cross-domain fields as triggers.

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

You can use custom queries to query the full GraphQL Admin API, not only [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metaobject).

**Caution:**

Every trigger in a `Metaobject` subscription must specify the metaobject type using `metaobject(type: '...')`.

## shopify.app.toml

```toml
[events]
api_version = "unstable"


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


topic = "Metaobject"
actions = ["update"]
triggers = [
    "metaobject(type: '$app:author').displayName",
    "metaobject(type: '$app:author').handle"
]


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


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

***

## Supported triggers

`Metaobject` subscriptions support the following field-level [triggers](https://shopify.dev/docs/api/events/latest#configuration).

### metaobject(type: String!)

Fires when events involve the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/unstable/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.

Collect details about changes to the object by subscribing to the trigger along with the `"update"` action, though it's recommended that you narrow your subscription to one of the other triggers below.

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

### metaobject(type: String!)​.displayName

Fires when the [`displayName`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Metaobject#field-Metaobject.fields.displayName) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/unstable/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

Fires when the [`field`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Metaobject#field-Metaobject.fields.field) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/unstable/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 `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​.value

Fires when the [`value`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/MetaobjectField#field-MetaobjectField.fields.value) field on the [`MetaobjectField`](https://shopify.dev/docs/api/admin-graphql/unstable/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

Fires when the [`handle`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Metaobject#field-Metaobject.fields.handle) field on the [`Metaobject`](https://shopify.dev/docs/api/admin-graphql/unstable/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 = "unstable"

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

  topic = "Metaobject"
  actions = ["create"]
  triggers = ["metaobject(type: '$app:author')"]

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

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

  ##### Payload

  ```json
  {
    "topic": "Metaobject",
    "action": "create",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/123",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": [
      "metaobject[type: '$app:author']"
    ],
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/123",
      "metaobjectType": "$app:author"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: create
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Metaobject/123
  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 = "unstable"

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

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: '$app:author').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/123",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": [
      "metaobject[type: '$app:author'].displayName"
    ],
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/123",
      "metaobjectType": "$app:author"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Metaobject/123
  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 = "unstable"

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

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: '$app:author').field(key: 'example-key')"]

  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

  ```json
  {
    "topic": "Metaobject",
    "action": "update",
    "handle": "metaobject-event",
    "data": {
      "metaobject": {
        "id": "gid://shopify/Metaobject/123",
        "handle": "example-metaobject",
        "displayName": "Example customer",
        "field": {
          "__typename": "MetaobjectField"
        }
      }
    },
    "fields_changed": [
      "metaobject[type: '$app:author'].field[key: 'example-key']"
    ],
    "query_variables": {
      "fieldKey": "example-fieldKey",
      "metaobjectId": "gid://shopify/Metaobject/123",
      "metaobjectType": "$app:author"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Metaobject/123
  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 = "unstable"

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

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: '$app:author').field(key: 'example-key').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/123",
        "handle": "example-metaobject",
        "displayName": "Example customer",
        "field": {
          "value": "…"
        }
      }
    },
    "fields_changed": [
      "metaobject[type: '$app:author'].field[key: 'example-key'].value"
    ],
    "query_variables": {
      "fieldKey": "example-fieldKey",
      "metaobjectId": "gid://shopify/Metaobject/123",
      "metaobjectType": "$app:author"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Metaobject/123
  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 = "unstable"

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

  topic = "Metaobject"
  actions = ["update"]
  triggers = ["metaobject(type: '$app:author').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/123",
        "handle": "example-metaobject",
        "displayName": "Example customer"
      }
    },
    "fields_changed": [
      "metaobject[type: '$app:author'].handle"
    ],
    "query_variables": {
      "metaobjectId": "gid://shopify/Metaobject/123",
      "metaobjectType": "$app:author"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-event-id: 44444444-4444-4444-4444-444444444444
  shopify-handle: metaobject-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-resource-id: gid://shopify/Metaobject/123
  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
  ```

***