Skip to main content

MetafieldDefinition

Requires read_content access scope.

Subscribe to field-level changes on the MetafieldDefinition 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 metafield definition, 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 MetafieldDefinition.

This example queries product metafield definitions using ownerType: PRODUCT. Change that enum value for a different owner type. You can't pass $metafieldDefinitionOwnerType here because Events supplies a String, while the GraphQL Admin API requires a MetafieldOwnerType enum. The fixed lookup doesn't restrict which owner types can trigger the subscription.

shopify.app.toml

[events]
api_version = "unstable"

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

topic = "MetafieldDefinition"
actions = ["update"]
triggers = [
"metafieldDefinition.name",
"metafieldDefinition.validationStatus"
]

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

query = """
query metafield_definition_details(
$metafieldDefinitionKey: String!
$metafieldDefinitionNamespace: String!
) {
metafieldDefinition(
identifier: {
key: $metafieldDefinitionKey
namespace: $metafieldDefinitionNamespace
ownerType: PRODUCT
}
) {
id
key
name
namespace
ownerType
validationStatus
}
}
"""

Anchor to Supported triggersSupported triggers

MetafieldDefinition subscriptions support the following field-level triggers.

Anchor to list-of-topics-metafieldDefinition.*
metafieldDefinition.*

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

metafieldDefinition.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition, including nested triggers. Use a more specific trigger to limit events to the fields you need.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.access.*
metafieldDefinition.access.*

Fires when the access field on the MetafieldDefinition object changes.

metafieldDefinition.access.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.access, 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 access field represents the access settings associated with the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.access.admin
metafieldDefinition.access.admin

Fires when the admin field on the MetafieldAccess 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 admin field represents the access permitted on the Admin API.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.access.customerAccount
metafieldDefinition.access.customerAccount

Fires when the customerAccount field on the MetafieldAccess 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 customerAccount field represents the access permitted on the Customer Account API.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.access.storefront
metafieldDefinition.access.storefront

Fires when the storefront field on the MetafieldAccess 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 storefront field represents the access permitted on the Storefront API.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.*
metafieldDefinition.capabilities.*

Fires when the capabilities field on the MetafieldDefinition object changes.

metafieldDefinition.capabilities.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities, 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 capabilities field represents the capabilities of the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.adminFilterable.*
metafieldDefinition.capabilities.adminFilterable.*

Fires when the adminFilterable field on the MetafieldCapabilities object changes.

metafieldDefinition.capabilities.adminFilterable.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities.adminFilterable, 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.

Indicate whether a metafield definition is configured for filtering.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.adminFilterable.enabled
metafieldDefinition.capabilities.adminFilterable.enabled

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

Indicates if the capability is enabled.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.adminFilterable.status
metafieldDefinition.capabilities.adminFilterable.status

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

Determines the metafield definition's filter status for use in admin filtering.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.analyticsQueryable.*
metafieldDefinition.capabilities.analyticsQueryable.*

Fires when the analyticsQueryable field on the MetafieldCapabilities object changes.

metafieldDefinition.capabilities.analyticsQueryable.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities.analyticsQueryable, 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.

Indicate whether a metafield definition can be queried in analytics.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.analyticsQueryable.enabled
metafieldDefinition.capabilities.analyticsQueryable.enabled

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

Indicates if the capability is enabled.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.cartToOrderCopyable.*
metafieldDefinition.capabilities.cartToOrderCopyable.*

Fires when the cartToOrderCopyable field on the MetafieldCapabilities object changes.

metafieldDefinition.capabilities.cartToOrderCopyable.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities.cartToOrderCopyable, 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 cartToOrderCopyable field represents the capability configuration for automatically copying values from a cart metafield to the corresponding order metafield when an order is created.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.cartToOrderCopyable.enabled
metafieldDefinition.capabilities.cartToOrderCopyable.enabled

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

Indicates if the capability is enabled.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.smartCollectionCondition.*
metafieldDefinition.capabilities.smartCollectionCondition.*

Fires when the smartCollectionCondition field on the MetafieldCapabilities object changes.

metafieldDefinition.capabilities.smartCollectionCondition.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities.smartCollectionCondition, 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.

Indicate whether a metafield definition can be used as a smart collection condition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.smartCollectionCondition.enabled
metafieldDefinition.capabilities.smartCollectionCondition.enabled

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

Indicates if the capability is enabled.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.uniqueValues.*
metafieldDefinition.capabilities.uniqueValues.*

Fires when the uniqueValues field on the MetafieldCapabilities object changes.

metafieldDefinition.capabilities.uniqueValues.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under metafieldDefinition.capabilities.uniqueValues, 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.

Indicate whether the metafield values for a metafield definition are required to be unique.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.capabilities.uniqueValues.enabled
metafieldDefinition.capabilities.uniqueValues.enabled

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

Indicates if the capability is enabled.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.constraints
metafieldDefinition.constraints

Fires when the constraints field on the MetafieldDefinition 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 constraints field represents the constraints that determine what subtypes of resources a metafield definition applies to.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.description
metafieldDefinition.description

Fires when the description field on the MetafieldDefinition 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 description field represents the description of the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.name
metafieldDefinition.name

Fires when the name field on the MetafieldDefinition 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 name field represents the human-readable name of the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.pinnedPosition
metafieldDefinition.pinnedPosition

Fires when the pinnedPosition field on the MetafieldDefinition 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 pinnedPosition field represents the position of the metafield definition in the pinned list.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.validationStatus
metafieldDefinition.validationStatus

Fires when the validationStatus field on the MetafieldDefinition 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 validationStatus field represents the validation status for the metafields that belong to the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Anchor to list-of-topics-metafieldDefinition.validations
metafieldDefinition.validations

Fires when the validations field on the MetafieldDefinition 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 validations field contains a list of validation options for the metafields that belong to the metafield definition.

Variables: metafieldDefinitionKey, metafieldDefinitionNamespace, metafieldDefinitionOwnerType

Was this page helpful?