Skip to main content

Customer

Requires read_customers access scope.

Supported actions: create, update, delete

Subscribe to field-level changes on the Customer GraphQL Admin API object.

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

[events]
api_version = "2026-10"

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

topic = "Customer"
actions = ["update"]
triggers = ["customer.addressesV2.*"]

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

query = """
query customer_event_payload($customerId: ID!) {
customer(id: $customerId) {
id
displayName
email
state
addressesV2(first: 10) {
nodes {
id
}
}
}
}
"""

Field-level triggers for Customer subscriptions.

All triggers require the read_customers 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 Customer. They can query the full GraphQL Admin API.

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

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

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

Variables: customerId

Anchor to list-of-topics-customer.addressesV2.*
customer.addressesV2.*

Fires when the addressesV2 field on the Customer object changes.

customer.addressesV2.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.addressesV2, 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 addressesV2 field represents the addresses associated with the customer.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.address1
customer.addressesV2.address1

Fires when the address1 field on the MailingAddress 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 address1 field represents the first line of the address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.address2
customer.addressesV2.address2

Fires when the address2 field on the MailingAddress 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 address2 field represents the second line of the address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.city
customer.addressesV2.city

Fires when the city field on the MailingAddress 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 city field represents the name of the city, district, village, or town.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.company
customer.addressesV2.company

Fires when the company field on the MailingAddress 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 company field represents the name of the customer's company or organization.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.countryCodeV2
customer.addressesV2.countryCodeV2

Fires when the countryCodeV2 field on the MailingAddress 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 countryCodeV2 field represents the two-letter code for the country of the address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.firstName
customer.addressesV2.firstName

Fires when the firstName field on the MailingAddress 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 firstName field represents the first name of the customer.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.lastName
customer.addressesV2.lastName

Fires when the lastName field on the MailingAddress 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 lastName field represents the last name of the customer.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.latitude
customer.addressesV2.latitude

Fires when the latitude field on the MailingAddress 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 latitude field represents the latitude coordinate of the customer address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.longitude
customer.addressesV2.longitude

Fires when the longitude field on the MailingAddress 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 longitude field represents the longitude coordinate of the customer address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.phone
customer.addressesV2.phone

Fires when the phone field on the MailingAddress 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 phone field represents a unique phone number for the customer.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.provinceCode
customer.addressesV2.provinceCode

Fires when the provinceCode field on the MailingAddress 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 provinceCode field represents the alphanumeric code for the region.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.addressesV2.zip
customer.addressesV2.zip

Fires when the zip field on the MailingAddress 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 zip field represents the zip or postal code of the address.

Variables: addressesV2Id, customerId

Anchor to list-of-topics-customer.amountSpent
customer.amountSpent

Fires when the amountSpent field on the Customer 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 amountSpent field represents the total amount that the customer has spent on orders in their lifetime.

Variables: customerId

Anchor to list-of-topics-customer.dataSaleOptOut
customer.dataSaleOptOut

Fires when the dataSaleOptOut field on the Customer 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 dataSaleOptOut field indicates whether the customer has opted out of having their data sold.

Variables: customerId

Anchor to list-of-topics-customer.defaultAddress
customer.defaultAddress

Fires when the defaultAddress field on the Customer 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 defaultAddress field represents the default address associated with the customer.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.*
customer.defaultEmailAddress.*

Fires when the defaultEmailAddress field on the Customer object changes.

customer.defaultEmailAddress.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.defaultEmailAddress, 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 defaultEmailAddress field represents the customer's default email address.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.marketingOptInLevel
customer.defaultEmailAddress.marketingOptInLevel

Fires when the marketingOptInLevel field on the CustomerEmailAddress 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 marketingOptInLevel field represents the marketing subscription opt-in level, as described by the M3AAWG best practices guidelines, received when the marketing consent was updated.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.marketingState
customer.defaultEmailAddress.marketingState

Fires when the marketingState field on the CustomerEmailAddress 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 marketingState field indicates whether the customer has subscribed to email marketing.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.marketingUpdatedAt
customer.defaultEmailAddress.marketingUpdatedAt

Fires when the marketingUpdatedAt field on the CustomerEmailAddress 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 marketingUpdatedAt field represents the date and time at which the marketing consent was updated.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.openTrackingLevel
customer.defaultEmailAddress.openTrackingLevel

Fires when the openTrackingLevel field on the CustomerEmailAddress 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 openTrackingLevel field indicates whether the customer has opted in to having their opened emails tracked.

Variables: customerId

Anchor to list-of-topics-customer.defaultEmailAddress.sourceLocation
customer.defaultEmailAddress.sourceLocation

Fires when the sourceLocation field on the CustomerEmailAddress 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 sourceLocation field represents the location where the customer consented to receive marketing material by email.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.*
customer.defaultPhoneNumber.*

Fires when the defaultPhoneNumber field on the Customer object changes.

customer.defaultPhoneNumber.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.defaultPhoneNumber, 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 defaultPhoneNumber field represents the customer's default phone number.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.smsMarketingConsent.*
customer.defaultPhoneNumber.smsMarketingConsent.*

Fires when the smsMarketingConsent field on the CustomerPhoneNumber object changes.

customer.defaultPhoneNumber.smsMarketingConsent.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.defaultPhoneNumber.smsMarketingConsent, 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 smsMarketingConsent field represents the SMS marketing consent information for the customer's phone number.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.smsMarketingConsent.optInLevel
customer.defaultPhoneNumber.smsMarketingConsent.optInLevel

Fires when the optInLevel field on the CustomerSmsMarketingConsent 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 optInLevel field represents the marketing subscription opt-in level that was set when the customer's marketing consent was last updated.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.smsMarketingConsent.sourceLocation
customer.defaultPhoneNumber.smsMarketingConsent.sourceLocation

Fires when the sourceLocation field on the CustomerSmsMarketingConsent 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 sourceLocation field represents the location where the customer consented to receive marketing material.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.smsMarketingConsent.state
customer.defaultPhoneNumber.smsMarketingConsent.state

Fires when the state field on the CustomerSmsMarketingConsent 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 state field represents the customer's current marketing consent state for this channel.

Variables: customerId

Anchor to list-of-topics-customer.defaultPhoneNumber.smsMarketingConsent.updatedAt
customer.defaultPhoneNumber.smsMarketingConsent.updatedAt

Fires when the updatedAt field on the CustomerSmsMarketingConsent 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 updatedAt field represents the date and time when the marketing consent was updated.

Variables: customerId

Anchor to list-of-topics-customer.firstName
customer.firstName

Fires when the firstName field on the Customer 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 firstName field represents the customer's first name.

Variables: customerId

Anchor to list-of-topics-customer.image
customer.image

Fires when the image field on the Customer 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 image field represents the image associated with the customer.

Variables: customerId

Anchor to list-of-topics-customer.lastName
customer.lastName

Fires when the lastName field on the Customer 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 lastName field represents the customer's last name.

Variables: customerId

Anchor to list-of-topics-customer.lastOrder
customer.lastOrder

Fires when the lastOrder field on the Customer 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 lastOrder field represents the customer's last order.

Variables: customerId

Anchor to list-of-topics-customer.locale
customer.locale

Fires when the locale field on the Customer 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 locale field represents the customer's locale.

Variables: customerId

Anchor to list-of-topics-customer.metafield(namespace: String!, key: String!).*
customer.metafield(namespace: String!, key: String!).*

Fires when the metafield field on the Customer object changes.

customer.metafield(namespace: String!, key: String!).* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.metafield(namespace: String!, 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 metafield field represents a custom field, including its namespace and key, that's associated with a Shopify resource for the purposes of adding and storing additional information.

Variables: customerId, metafieldKey, metafieldNamespace

Anchor to list-of-topics-customer.metafield(namespace: String!).*
customer.metafield(namespace: String!).*

Fires when the metafield field on the Customer object changes.

customer.metafield(namespace: String!).* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under customer.metafield(namespace: 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.

This subscription omits the optional argument metafield.key.

The metafield field represents a custom field, including its namespace and key, that's associated with a Shopify resource for the purposes of adding and storing additional information.

Variables: customerId, metafieldKey, metafieldNamespace

Anchor to list-of-topics-customer.metafield(namespace: String!, key: String!).value
customer.metafield(namespace: String!, key: String!).value

Fires when the value field on the Metafield 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 data stored in the metafield.

Variables: customerId, metafieldKey, metafieldNamespace

Anchor to list-of-topics-customer.metafield(namespace: String!).value
customer.metafield(namespace: String!).value

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

This subscription omits the optional argument metafield.key.

The value field represents the data stored in the metafield.

Variables: customerId, metafieldKey, metafieldNamespace

Anchor to list-of-topics-customer.multipassIdentifier
customer.multipassIdentifier

Fires when the multipassIdentifier field on the Customer 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 multipassIdentifier field represents a unique identifier for the customer that's used with Multipass login.

Variables: customerId

Anchor to list-of-topics-customer.note
customer.note

Fires when the note field on the Customer 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 note field represents a note about the customer.

Variables: customerId

Anchor to list-of-topics-customer.numberOfOrders
customer.numberOfOrders

Fires when the numberOfOrders field on the Customer 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 numberOfOrders field represents the number of orders that the customer has made at the store in their lifetime.

Variables: customerId

Anchor to list-of-topics-customer.productSubscriberStatus
customer.productSubscriberStatus

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

Possible subscriber states of a customer defined by their subscription contracts.

Variables: customerId

Anchor to list-of-topics-customer.state
customer.state

Fires when the state field on the Customer 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 state field represents the state of the customer's account with the shop.

Variables: customerId

Anchor to list-of-topics-customer.tags
customer.tags

Fires when the tags field on the Customer 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 tags field represents a comma separated list of tags that have been added to the customer.

Variables: customerId

Anchor to list-of-topics-customer.taxExempt
customer.taxExempt

Fires when the taxExempt field on the Customer 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 taxExempt field indicates whether the customer is exempt from being charged taxes on their orders.

Variables: customerId

Anchor to list-of-topics-customer.taxExemptions
customer.taxExemptions

Fires when the taxExemptions field on the Customer 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 taxExemptions field represents the list of tax exemptions applied to the customer.

Variables: customerId

Anchor to list-of-topics-customer.verifiedEmail
customer.verifiedEmail

Fires when the verifiedEmail field on the Customer 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 verifiedEmail field indicates whether the customer has verified their email address.

Variables: customerId


Was this page helpful?