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.

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

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
metaobject(type: String!).field

Fires when the field 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 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.value
metaobject(type: String!).field.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?