Skip to main content

Metaobject

Requires read_metaobjects access scope.

Subscribe to field-level changes on the Metaobject GraphQL Admin API object. You can subscribe to create, delete, and update events, and to changes to specific fields.

Each topic 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.

Caution

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

shopify.app.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
}
}
"""

Anchor to Supported triggersSupported triggers

Metaobject subscriptions support the following field-level triggers.

Anchor to list-of-topics-metaobject(type: String!).*
metaobject(type: String!).*

Fires when events involve the 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

Anchor to list-of-topics-metaobject(type: String!).displayName
metaobject(type: String!).displayName

Fires when the displayName field on the 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

Anchor to list-of-topics-metaobject(type: String!).field(key: String!).*
metaobject(type: String!).field(key: String!).*

Fires when the field field on the 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

Anchor to list-of-topics-metaobject(type: String!).field(key: String!).value
metaobject(type: String!).field(key: String!).value

Fires when the value field on the 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

Anchor to list-of-topics-metaobject(type: String!).handle
metaobject(type: String!).handle

Fires when the handle field on the 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

Was this page helpful?