RFC: Standardized Storefront DOM Event Payloads

[stephanie-shopify]

Author: Shopify
Expected end date: November 3, 2025

This RFC proposes patterns and payload structures for standardized storefront DOM events. To enhance developer experience and improve storefront performance, we recommend including a curated subset of essential object data directly in event payloads.

As we introduce new standard DOM events for storefronts, a critical question is what data should be included in the event payload. The decision directly impacts both app developers and storefront performance.

If we only emit resource IDs (e.g., productId), every consuming app will likely make an immediate Storefront API call to fetch the object's details. These calls will likely be redundant and all at the same time.

Conversely, we must be careful not to include too much data, as this can also negatively impact performance by requiring the theme to render large objects in Liquid, much of which may go unused. We'd like to find the right balance, making events useful for developers without compromising the performance of the merchant's storefront.

The goal is to provide enough data to cover ~80% of common use cases out-of-the-box. This approach aims to avoid performance issues while still empowering developers, and it serves as the basis for gathering community feedback before final implementation.

1. Problem

As we introduce new standard DOM events for storefronts, we need to determine what data should be included in event payloads. This decision directly impacts both app developers and storefront performance.

Challenges:

• Too little data: If events only contain resource IDs, every consuming app will make immediate Storefront API calls to fetch object details, leading to redundant requests and poor performance.
• Too much data: Including excessive data requires themes to render large objects in Liquid, much of which may go unused, negatively impacting performance.

We need to find the right balance, making events useful for developers without compromising merchant storefront performance.

2. Proposal

We propose events include a predefined, essential subset of the primary object's data directly in the event payload (e.g., event.product.id, event.product.title, event.product.price).

The goal is to provide enough data to cover ~80% of common use cases, allowing developers to immediately use the event without a follow-up API call. For the remaining, more specialized use cases that require fields not present in the payload, developers can use the provided IDs to query the Storefront API for additional information. Additionally, theme developers can choose to include extra information under event.detail.

This approach strikes a practical balance between the performance cost of fetching data and the developer experience benefits of having rich, contextual data readily available.

2.1. Design Patterns

To ensure our events are consistent, easy to use, and extensible, we will follow a clear set of design patterns.

Event Naming Convention

Event names will follow a simple and predictable category:action structure in present tense. This makes events easy to discover and understand.

Examples:

• product:view
• search:submit
• user:sign-out

Event payloads will be modeled after the GraphQL Storefront API where possible, using camelCase naming for properties and including a curated set of nested objects for essential context. For example: event.product.title

Event Creation and Consumption

To simplify emitting events, we will provide helper classes for theme developers. For consumers (app developers), these are standard browser events that can be listened to with plain JavaScript, requiring no special libraries.

Note: The delivery method of these classes is still to be determined (global classes or a module with import maps).

Creation (for Theme Developers):

const event = new ProductViewEvent({
  product: productObject,
  context: 'search'
});
document.dispatchEvent(event);

Consumption (for App Developers):

document.addEventListener('product:view', (event) => {
  console.log('Product viewed:', event.product.title);
});

Standard and Custom Payloads

Each event helper class will accept a set of standard properties (e.g., context, product, cart) which are then made available under the event object directly. For custom use cases, theme developers can pass arbitrary data under a detail property.

new ProductViewEvent({ ..., detail: { customData: true })
document.addEventListener('cart:updated', (event) => {
    console.log('Custom:', event.detail.customData);
});

Context for Granularity

To reduce the total number of event names and provide more granular insight, we propose an event.context property. This helps distinguish where a common action originated.

For example, a product:view event could be emitted from multiple places. The context property clarifies the source without needing separate events:

document.addEventListener('product:view', (event) => {
  if (event.context === 'search') {
    // Product viewed in search
  }
});

Event Timing

While event timing is specific to each action, we propose a pattern for asynchronous operations like updating the cart. For these events, we will dispatch them immediately, before the async action starts.

The payload will include a promise that mirrors the action's lifecycle, giving developers the flexibility to run code before and after the action.

document.addEventListener('cart:add', (event) => {
  // Run logic before item is added to cart here
  event.promise
    .then(() => {
      // Run logic after item is added to cart here
    })
    .catch(() => {
      // Run logic when the action fails
    })
});

2.2. Common Objects

Event payloads will reference standard Storefront API object types. Note that not every property in these objects need to be available in the events but they are a general reference:

• MoneyV2 (Price)
• SelectedOption (Variant)
• CartCost
• CartDiscountCode
• CartDiscountAllocation
• Product
• ProductVariant
• ProductFilter
• SearchSortKeys
• Collection

When a property type is defined in one event, the following events assume the same type for similar properties unless stated otherwise.

2.3. Event Specifications

The following contains a list of events with their proposed properties based on the GraphQL Storefront API. The use cases listed are examples of how these events will be used by consumers so that we cover the most typical scenarios.

Page Events

page:view

Any page or route is viewed.

Properties:

• page
  • template The template/type of the page. For example, “product” or “index”.
  • url Full URL of the page.
  • title Desired title. It doesn’t need to match the tab title.

---

Product Events

product:view

Product becomes visible (page, search, collection, ad).

Properties

• context page | search | collection | dialog | recommendation
• product
  • id
  • title
  • handle
  • selectedOrFirstAvailableVariant
    • id
    • title
    • availableForSale
    • price MoneyV2
    • selectedOptions Array of SelectedOption

product:select

Product variant is selected.

Properties

• variant
  • id
  • title
  • availableForSale
  • selectedOptions - Array of SelectedOption
  • price - MoneyV2
  • product
    • id
    • title
    • handle

---

Cart events

cart:view

Cart is viewed either in a modal or a full page.

Properties

• context page | dialog
• cart
  • id
  • totalQuantity
  • cost subset of CartCost fields
    • totalAmount MoneyV2
  • lines[] Array of subsets of CartLine
    • id
    • quantity
    • cost
  • discountCodes[] Array of CartDiscountCode

cart:lines-update

Items modified in cart

Use cases

• Optimistic UI

Properties

• cartLines[] Array of subsets of CartLine
  • id
  • quantity
• action add | remove | update
• promise Resolves to:
  • cart
    • id
    • totalQuantity
    • cost subset of CartCost fields
      • totalAmount MoneyV2
    • lines[] Array of subsets of CartLine
      • id
      • quantity
      • cost

cart:error

When cart mutation returns an error

Properties

• error
• code

cart:discount-update

Discount code applied.

Properties

• cart
  • id
  • totalQuantity
  • cost subset of CartCost fields
    • totalAmount MoneyV2
  • discountCodes[] Array of CartDiscountCode

---

Search & discovery events

search:submit

Search is submitted.

Use cases

• There are apps that try to hide search results (same with collections). E.g. Only logged in customers can see products, or customers with a certain tag. Hiding them is often done in Liquid file modifications.

Properties

• search
  • query
  • productFilters? Array of ProductFilter
  • sortKey? SearchSortKeys
• context header | page | dialog
• promise Resolves to:
  • totalCount

search:update

Search filters/sort change

Properties

• search
  • query
  • productFilters? Array of ProductFilter
  • sortKey? SearchSortKeys
• promise Resolves to:
  • totalCount

---

Collection events

collection:view

Collection is viewed

Use cases

• Apps hiding products (see search example)

Properties

• collection Subset of Collection object
  • id
  • handle
  • productCount

collection:update

Collection filters/sort change.

Properties

• collection
  • id
  • productCount
• filters
• sort

---

User events

user:sign-in

User signs in

Properties

• method: email | social | shop

user:sign-out

User signs out

Properties

• sessionDuration

user:update

User profile updated

Properties

• fields[] String array
• context: profile | checkout

---

Consent events

consent:update

Consent preferences change

Properties

• accepted_categories Array of analytics | marketing | personalization
• rejected_categories Array of analytics | marketing | personalization
• action accept-all | reject-all | accept-some
• context banner | preferences

consent:view

Consent UI viewed

Properties

• context: banner | preferences

3. Feedback Requested

We are seeking feedback from the developer community on:

1. Payload completeness: Do the proposed payloads cover your common use cases? What fields are missing that you would frequently need?

2. Payload size: Are we including too much or too little data in any of the events?

3. Event naming: Are the event names intuitive and discoverable?

4. Design patterns: Do the proposed patterns (context property, promise for async operations, custom detail field) meet your needs?

5. Open questions: Input on any of the open questions listed above

6. Additional events: Are there important events missing from this specification?

[bakura10]

Hello,

Thanks a lot for this, that's awesome and something that should have been done years ago (but better later than never!). The set of events sound nice to me. I would however add the following:

• cart:note-update : triggered when the note changes
• Is the context standardized? In our themes, we currently have an event variant:add and cart:change and line-item:change. We use the variant:add to open the cart drawer. Here everything would be merged into a unified cart:lines-update, but I would need to be able to distinguish the origin.

One important thing is that themes should be required to use those events as well. One very common use case for apps is that they have their own "Add to cart" button and want to be able to open the theme cart drawer. This means that not only theme dev, but also app dev should use those events and trigger them, and themes must listen to those events instead of their own one.

One extra question: how exactly the trigger would work? In the example you gave:

const event = new ProductViewEvent({
  product: productObject,
  context: 'search'
});

Does this mean it is the responsability of the theme/app dev to send the productObject? How can you guarantee that all the payload is properly set?

[PaulNewton]

cart:update > context: note ?
cart:update > context: attributes
or if really going for API parity or cart:update > context: customAttributes(graphql)
or cart:update > context: note_attributes(webhooks)

Though I'm VERY wary about things polluting outside the .detail property as that already causes confusion.
Unless were gonna enforce distinguishing between initializing and post-initializing properties.

[TeamDijon]

Sadly, relying too much on the detail property nullifies the standardization. If the standard event does not include most of the use-cases right out of the gate, every developer will just have a custom interface via .detail, leaving the app developers in the same position as before, RFC is greatly appreciated !

[PaulNewton]

every developer will just have a custom interface via .detail

That's already common with also polluting the top level at the same time because of the lack of standard.
.detail is a single consolidated place to look for data, or problems.
Same issue as having to root around the window for custom props.
If it's at least on something like window.theme conflicts minimize from non-standard and somewhat approach proper namespacing.

[benjaminsehl]

cart:note-update

Would love to hear about the app use case for this, but yes I think it's safe for us to provide complete coverage for all of the SF API cart Update mutations (including Note, Attributes, etc.) in the spec. Cart is the place this spec is most needed and so we likely should have v1 of the spec fully cover those events.

Is the context standardized.

Yes — please provide any feedback on use cases you want to see covered here. Generally we've been considering template types, and element types (like dialog instead of mini-search).

The ability to distinguish the origin is exactly why context is being introduced.

One important thing is that themes should be required to use those events as well.

Yes — the intention here is that both Themes and App Extensions will be required to use this standard to guarantee interoperability.

Does this mean it is the responsibility of the theme/app dev to send the productObject?

We're still exploring the DX for this — but outside of detail the "guaranteed" shape will be provided by Shopify. Likely via a Liquid filter on the object (e.g. {{ product | event_data }} — WIP.

---

To the remainder of the discussion about detail — it's really there for needs that are theme specific, but not critical to App Blocks.

We will intentionally keep the payloads as small as we can, and evolve them over time as we see patterns & use cases emerge. This can be thought of as v1 of the spec, which we expect to cover the most critical needs, not every need … and over time we'll expand it whenever we're confident. This is a great place for the ecosystem to stay involved over time.

BTW — we'll have all future discussions on community.shopify.dev; so in the future you can feel free to make posts there and suggest improvements. (This should have been over there too, but too late now!)

[PaulNewton]

cart:note-update
Would love to hear about the app use case for this

The most reductive is validation, making sure the note isn't empty when it's required; deleting or rejecting it

More esoteric one-offs so I don't know if I'd give them a lot of weight:

• applying the note to line item properties
• "shared" carts & draft orders
• ERP's , greeting cards fields, having to stuff the cart note with other data before checkout , after a customer has edited the note.
• Stripping special characters, like emojii's or unicode that downstream systems can't handle or filter out.

[gideonb]

Thanks @stephanie-shopify — I'm thrilled to see some standardization here.

Zooming out a bit, I am unsure who emits the events. Like @bakura10, I currently emit a subset of these. These look like events that Shopify could emit — nearly everything is a form submission or a pageload. I also see the Creation (for Theme Developers): section.

The case @bakura10 mentioned above is surprisingly tricky. When an app adds to the cart, the cart needs to open.

Why this is hard:

• There is usually more than one cart. I show a mini-cart popup on ATC, but show a cart-drawer when the user clicks the cart icon in the header. Some stores link to a cart-page from the cart-drawer; usually for logged-in pricing discounts, shipping estimates, wishlist, etc.
• What happens on ATC is contextual, and the context can stack. If a product is added from the product page, I will probably open a popup or the cart drawer. If a product is added from a cart drawer upsell, I typically keep the cart open and refresh the cart. If a product is added from the cart page, I don't open the cart drawer, I refresh that page. It gets tricky with quickview. A product form inside a modal will stack the context variable into cart>quickview or product>quickview where cart>quickview refreshes the cart and product>quickview opens an unobtrusive notification popup. All of these have different animations so they can't be collapsed into one layer of context.
• This event is pointing in the wrong direction. All the proposed events are fired by themes towards apps. This event goes the other way. The naming structure needs to specify the "direction" of the event in a very clear way.

I honestly don't have a solution for this "direction" thing. These are my best ideas so far:

1. who:category:action - The events could go both ways. Unless we bake that into our naming convention from the start, nobody will remember whether product:select means "hey app, this product was just selected" or "hey theme, please select this variant". All the events listed here would be theme:category:action and the case I outlined above would be app:product:add or app:cart:open. Or maybe the opposite names? This is genuinely hard.
2. window.themeState.cartOpen - Maybe we store application state somewhere apps can mutate it and disconnect the events from state? That model would fit with a non-directional event API, but it feels like moving the hard complexity to a different pile. It would work great for opening a cart, but it won't map well into an ATC popup notification with a 5-second timer.

The directionality problem is tricky. As a theme developer, it's unclear what I should do when cart:lines-update fires while the cart is closed, or collection:view fires from the homepage. If I do nothing, I don't think this API will solve the core issue for app developers.

[PaulNewton]

who: is interesting, but possibly troubling, as you now would have multiple event listeners for the same purpose.'

who: is good enough for the theme editor, e.g. shopify:section:load begets app:section:load

as Shopify isn't injecting anything into the theme to make this happen
... it requires opt-in to begin leveraging..

This is what isn't clear, who is doing what and why?
None of this matters without the enforcement mechanism.
Merchants aren't gonna be evaluating event busses en-masse to vote with their wallet*.
It's not even clear upfront a main goal is for apps getting first class conveniences.

If this is a theme-store requirement*, ?retroactive?, theme events are first-class so name spacing doesn't even make sense.
Shuffling source clues to the context et al stuff.
If shopify, or apps, are injecting things ownership should be declared, so MUST be name spaced ⚖️🏛️👨‍⚖️█▬▬:
Simplicity benefits by upfront clarity, not rooting around a debugger in abstractions of vague simplicity.

Themes standardization priority should be to benefit merchants theme needs , where any niceties for apps are a side-effect.
This is the kinda of thing I wish shopify could put in merchants inboxes about integration issues but how many gonna know event names without a 99:1 noise ratio /shrug.
A current parallel is probably the ?variant parameter; themes may or may not use it , or even implement it, and the problems that causes for merchants even though there should be a "callback" at least(if you can find it). Before even moving to app integrations.

Habitual misprioritization of who is supposed to be benefiting continually leads to frontend klunkiness and confusion e.g. see every support/post confused about metafields and MOBs not working because of a missing .value barnacle. Or every merchant that equates /cart and checkout as the same words so don't understand why they can't edit checkout.

*huehuehue fourth party themes gonna be caught lacking huehuehue

[benjaminsehl]

Thanks for your thoughts here — I really appreciate your enthusiasm and candor, as always.

We're not writing off namespacing, it very may well ship — but we do want to keep things as ruthlessly simple as we can and there will be some tradeoffs that come with that.

Here's some missing context that should have been in the RFC when we released it. We will update it to be clearer.

1. The primary goal for us with standardized events is to better support interoperability of app blocks, such that you can easily swap out first party apps like consent banners for third party options. Niceties for apps are not a side-effect.

2. We will consider name spacing for the reason that app blocks may look for payload details and forget to null check — that is the most convincing argument so far — but I would have rather had a simple DX solution this. Both the DX for populating payloads and consuming them should have been addressed in the RFC, and so we'll be updating that.

3. When we shipped Horizon there were many app blocks that didn't work with it right away — and there wasn't much we could do; app developers then needed to rush to update their apps. So all of this is a problem that already exists today — creating this standard is a way to create a happy path that avoids this issue in the future. It will not take the issue to 0% overnight and that's an over-reach as a goal that would come with many tradeoffs.

[ceri-waterscreative]

Hi @benjaminsehl - I think you underestimate the benefits this would provide to Theme Developers, the amount of work arounds that are needed for themes that do not have built-in events is simply upsetting, we literally try and avoid themes that don't dispatch their own events as these are seen as "not developer friendly".

The new native events would technically make every theme 'developer friendly' and change the way in which we go through our theme picking process.

However, I need to re-iterate with the naming conventions as they are, there would be breaking changes for the majority of themes that are developer friendly. This wouldn't be just those that are customized, many theme developers use Custom Events to keep their Web Components states in sync, i.e. say there's a Cart Icon which changes appearance when there's items in the basket, well that just listens out for a custom event. If you were to dispatch the native events as is, those themes would likely break and throw errors as the payload would be different - or if we're lucky the updates would occur twice, which isn't great for performance.

[msev]

I completely agree with @ceri-waterscreative

Events must be prefixed with shopify:, like those dispatched in the theme editor (shopify:section:select, shopify:block:select, etc.).

In our custom themes, we already use a lot of custom events (cart:add:success, cart:update:success, product:variant:change, product:quantity:change, etc.), so we don't want anything to break.

[TeamDijon]

To be fair @ceri-waterscreative, this is a breaking change, and should be treated as such.

But let's say a year from now on, given the native events don't miss the mark; the themes and web components will evolve to use these and progressively enhance from there. As long as this RFC and further discussions get the job done, we should be good. And for some events, there is a need for serious discussion ahah

Still onboard for the namespacing/property or a way to discriminate between events, so that backward compatibility is mitigated for custom builds that do not wish to evolve for now.

[ceri-waterscreative]

Really happy to see this, I think the Event Naming Convention needs to include an additional prefix however i.e. 'shopify:product:view' because theme devs like myself have already dispatched our own events with the same naming conventions, with the different payloads this would be a breaking change.

[stephanie-shopify]

good call out, thanks @ceri-waterscreative

[benjaminsehl]

See my note above here: #2002 (reply in thread)

I'm curious for your take on this @ceri-waterscreative & @PaulNewton.

You're correct that this is, in a sense, a proposal for a breaking change — but only to an API contract that never existed in the first place. App Blocks have never had a guaranteed way to listen to events, and so this is just formalizing that contract.

I don't believe you should have two themes fire events for the same purpose.

We still need to share the DX for this — but in the lightest possible implementation you could pass the standard payload object we provide you into the event you already have, and then App Blocks would just start working.

Feel free to tell me if I'm off my rocker on this one! I might not have enough context to understand what implication this would have for your theme code.

[PaulNewton]

a new contract with problems is a breaking change

I don't believe you should have two themes fire events for the same purpose.

This only works if purpose is synonymous with endpoint, which can be a useful/reductive rubric to ship faster.
Is a bundler/personalization app updating the cart async from interactivity on any page the same purpose as the add-to-cart button on the PDP.
If were going full compiler jock to make primitives then yeah there's no difference; same as minifiying javascript: !1 == false.

[ceri-waterscreative]

@benjaminsehl Mm you keep mentioning App Blocks but if these events are going to be dispatched to the DOM it will impact theme developers too.

To make themes "developer friendly" many have included standard events such as "cart:update" as a means to allow developers to extend a themes functionality, i.e. do something after the cart updates without the need of an Intersection Observer and horrendous JS to track what's being changed on the cart.

The DOM is going to have a lot of events from theme developers already, so to introduce new events with a naming convention that is likely going to have conflicts will in fact be a breaking change, because theme developers will then have to change their naming conventions and update their themes.

I.e. imagine if you chose the same event name/namespace as an event that a popular theme like Prestige utilized, you'd have a ton of stores suddenly throwing JS errors because the payload is different or a slightly better case scenario (but not great) functionality starts triggering twice.

There's genuine cases for using DOM events in development too, i.e. lets say you have a cart badge in the header which is a Web Component, it could in fact listen out for a "cart:update" event and when it detects changes update its appearance to include a count.

[benjaminsehl]

I hear you @ceri-waterscreative — I stated this here, but this is a compelling argument for name-spacing that I agree with. We'll consider this.

In a dream world everyone defensively codes and nullchecks … but I realize that's not the case.

For what it's worth, I am fully aware that themes do this today, Horizon follows a very similar pattern to this spec already today.

I keep mentioning App Blocks because the most important problem we believe in solving here is interoperability, so that, exactly as you say app block developers don't have to do hacks to figure out when things update.

One thing I think you're saying that I didn't fully appreciate previously though is that this is also very helpful for people who are tweaking existing themes via custom code and want to add additional functionality while hooking into an event system. I had always been focused on the API boundary between Many:Many Themes:Apps … not 1:Many Theme:Theme developers.

[PaulNewton]

I'm 100% for consistency in shopify outputs, but how many frontend devs are never gonna see this because this is a server technology repo.

Besides as an initial gauge*, is there any deeper reason for using the liquid repo though for shopify DX?
e.g. what actual outcome here would be turned into a pull request for this repo.

Like is there some unmentioned tight coupling coming to liquid itself based on conventions around the shopify owned ajax api.
such as SSE(server sent events)... or dynamic object creation.. etc

*versus making .dev forum RFC, or the storefronts repo.
or a new repo specifically about ALL frontend surfaces: theres now ~4 theme paradigms on github atm , then there's platform liquid v ajax api, the storefront apis,etc; it has become quite the diaspora

[stephanie-shopify]

https://community.shopify.dev/t/rfc-standardized-storefront-dom-event-payloads/24369

[benjaminsehl]

Hey Paul — thanks for this, fully agree. We should have had the source of truth for this be in community.shopify.dev to begin with and will do so moving forward for anything outside of the Liquid spec.

[bkspace]

Love this - especially the event timing for things like cart:add.

[TeamDijon]

Grateful to see some proper RFC on this topic :) Don't hesitate to do these more frequently, we can't get enough !

I think it's a solid and welcome start. There is definitely a need and there are real challenges along the way. As a consequence, I would advise not to rush implementation and start by recommending payload versioning, not to fall into backward compatibility paralysis ! Versioning following other APIs would be coherent in my opinion.

Regarding the list of events available, while I would recommend to focus on a limited set during the planning phase (page:view, product:view, collection:update and most importantly cart:update for example), a lot of new ones can be introduced to benefit different partners. Not in a particular order, with varying criticality, some examples:

• wishlist:view and wishlist:add/remove for the wishlist functionality
• review:view and review:submit for the rating functionality
• comparison:view and comparison:update for products comparison functionality
• chatbot:view, chatbot:message for customer service and potentially AI interface evolutions in the future
• quickview:open/close as @gideonb suggested could use a little digging
• quick-add/quick-shop for 1-click shopping and Shop pay (aka bypassing the cart entirely)
• Maybe navigation:open/close for menus and pagination:change for paginating
• notification:back-in-stock, share:product, recommendation:view. You get the gist, no limits to what can be done ahah

Namespacing is also a good recommendation, something simple like shopify, theme, app (or same as Shopify docs) and user (?) for client interaction seems like a logical starting point (if AI does not change the rules ahah)

For the problems highlighted by @bakura10 and @gideonb, mostly regarding add to cart UI consequences, I would maybe recommend defining the context property as an array, making it easier to communicate the intent, for example:

const event = new CartUpdateEvent({
  cartLines: [...],
  action: 'add',
  context: ['upsell', 'quickview', 'product_page'],
  detail: {...}
});

In this example, the intent would be to add an upsell product from inside a quick-view modal from the product page (context ordered from most to least specific). I think it gives more flexibility to react accordingly. Again, just like the different events, it's hard to know when to stop, so just throwing out the idea.

Regarding the UI consequences of some actions (adding to cart, applying filters ...), I think creating a standard reflected in theme settings could be a way to bridge the gap between theme and app developers, here's an example:

// settings_data.json extract
{
  "add_to_cart_ui_hint": "cart_page" | "cart_drawer" | "notification"
}

const event = new CartUpdateEvent({
  cartLines: [...],
  action: 'add',
  context: [...],
  uiHint: Shopify.theme.AddToCartUiHint // settings_data value
  detail: {...}
});

Not totally sure on this but if main patterns can be explicited, app developers could hook on that to update the event payload, leading to the correct UI consequence, independently of the theme. There are risks to discourage new patterns on the theme store if the structure becomes too rigid, so I'm not sure how to find the right balance on this. Also, on a more technical aspect, what about bubbling and propagation, will this be evaluated on a per event basis, can this be overriden ?

Also, for cart update operations and many other actions, many specifics and context-dependent factors are to take into account, so the system would need to be extensible for developers but standardized on the basic level to be theme-agnostic and usable at the most basic level (add to cart from product page).

This RFC and the events are clearly geared towards themes for now, but what about extensibility (user events are in the initial RFC after all), is there a strategy of adopting them there as well, maybe have standardized checkout events as well ? Is this in the global scope, who has the responsibility of sending these ?

Lots of suggestions, on which I can add to extensively integrate partners on the error, testing and validation aspects of this central feature, which are absent from this early RFC but will be important later down the road. Hope this has been helpful, good work launching RFC, we need more of them !

[PaulNewton]

Not a fan of context being anything other than a simple string; with or w/o a colon naming convention.
context(string) vs contexts(array) , vs other namings like intents

If there has to be a stacked-context are we kinda stuck with array handling, and a need for utilities.
As context being an Object seems overkill even though the soft colon naming convention everyones getting used to pulls from Objects/JSON thinking; /shrug that's js.

The priority order I could go either way on. context[0] vs context[context.length-1] still gonna burn people

stacked-context: for anything more more than event.target+context , or string parsing a single string context=>intent:component:surface:namespace, or making more context vars context>currentContext lol.

wishlist:view and wishlist:add/remove for the wishlist functionality
review:view and review:submit for the rating functionality
comparison:view and comparison:update for products comparison functionality

🚲🏚 IF this extended to apps,
Similar to standard metafield definitions https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-standard-definitions

This would be the type of thing I would like to see at the app config/TOML level to surface in the app store listings, the theme editor, etc to remove guesswork about fourth party apps behavior.
Digging through some apps anemic docs or event bus to figure out HOW it integrates with themes isn't an effective use of time.

[benjaminsehl]

Thanks @TeamDijon — we'll definitely evolve this spec over time. Important for us to keep it tight at launch.

I've responded to a couple of the other threads on some of the overlapping things.

On context — it's important that this is just a string to keep things simple and make it easy for devs to do a switch case statement, for example.

It's also important to keep things simple and named so that we can have clear types for things — this makes it possible for us to add standard events to our VS Code extension, for example, so you can get a nice intellisense experience throughout and not even need to remember what the API shape is.

Regarding extensibility — sandboxing of extensions doesn't allow for DOM events to be passed the same way, but yes we're considering that and we intend to have a single standardizing event schema that we can use across Shopify.

[andershagbard]

I have not seen Market properties mentioned yet. It's a really needed for marketing attributing across regions

[benjaminsehl]

Curious to hear more about this, but I should mention that standardized events are meant specifically for interoperability with app blocks — NOT for analytics. Analytics will always be served by Web Pixels.

If there is anything holding you back from using Web Pixels I'm happy to make that known to the team.

[ceri-waterscreative]

I've now reviewed the properties and..

cart:view
I feel that this needs variantid on the lines

cart:attribute-update
We don't have any event if a cart attribute is updated

cart:update
I feel that a general cart:update which just passes the payload and call type could be very handy
That way you can determine what is being changed i.e. just line item properties?

product:select
This should really include line item properties or selling plan Ids

[benjaminsehl]

We had considered a single cart:update event, or multiple events. I think this decision may still be worth revisiting.

Generally we've been following the path of mapping the events to match the equivalent SF API mutations — cart:attributes-update maps well to cartAttributesUpdate and so could be considered.

Agreed we need variant information on the cart line, including critical information like the product title, options selected, and featured image. It's a mistake that this wasn't included in the RFC — thanks for pointing it out.

Line item properties & selling plan IDs — can you provide a use case for what you need in the theme to do this? Specifically as it relates to theme app extensions?

[PaulNewton]

Isn't the whole point of this to cover theme standardized events for i.e. 80% of scenarios?

Inventory for availability is in how many scenarios, yet is gutted from the ajax api and not coming back.
Security & Performance defaults beat our wants all the time no matter how silly it is.

If a site is using a lot of LIPs then it's more than likely already passing that data through the stack in some horrendous way.

Yes by querying the PDP form, or the /cart.json, since there is no /cart-lips.json endpoint etc

[PaulNewton]

cart:attributes-update maps well to cartAttributesUpdate

Vs cart:attributes:update (lowerCamelCaseWords becomes colon:case:words) or cart:attributesUpdate(sticking to lowercasing event names)
and a contrived example problem if forcing kebab-case: user:sign-in-update /bleh
How dedicated to this format have things gotten.
New devs are hopping between so many different naming conventions now a days even in one vertical it's a small book on the when & why's when moving between surfaces or fullstack.
probably should be it's own thread /shrug.

[ceri-waterscreative]

@benjaminsehl So an example would be bundles, personalised products and addon products such as Gift Wrapping.

A lot of Apps and solutions use Line Item Properties to handle the information for these and often we have to find ways of hijacking a "cart update" event to ensure that i.e. the personalised product is valid, the addon product has the correct properties and so on.

I have Gift Wrapping, Gift Boxes and Personalised items done via theme updates on probably over half of the sites we work on.

[benjaminsehl]

Thanks @ceri-waterscreative — that's great context.

By the way - the reason I keep mentioning "as it relates to apps" is because we have the detail object as an escape hatch for themes, so we fully expect this to not cover all scenarios and we will default to having less coverage up front, for the benefit of a more durable API in the long term.

As we see demand grow / common patterns emerge over time, we'll evolve the spec.

[si-khooks]

Hello. Why not just expose the existing standardized analytics events to the front-end? The lack of this feature caused us to create a custom pixel that just pipes these events to the main window, and then we handled them in an app-embed block anyways; since a lot of tracking pixels (e.g. FB, Google, Bing) require direct access to the top-level DOM (i.e. neither custom pixels nor app pixels worked).

Or create a type of pixel that's allowed to run in the main window context + checkout. Right now getting consistent event handling everywhere requires a mix of solutions depending on access to the main window context and to analytics events (i.e. only pixels in checkout, which can't render in the main DOM, and the requirement for a custom pixel that passes events to the main window for an app embed block so it can both access the main window and receive analytics events).

[benjaminsehl]

Hey there — these events are meant solely for UI purposes, not analytics. It's important that analytics/pixel events are sandboxed and we'll be continuing that policy regardless of this proposal. That said, I'm sending on this feedback to our Web Pixels team — this is great to know. They're also a part of this discussion and will be looking into any relevant updates that might be needed as a result of where we land. If there's any example code in a gist or similar that can provide more context of the workarounds you're having to do today, I'd love to see it and pass it on to the Web Pixel team.

[si-khooks]

Hi @benjaminsehl. This is what we're doing in our custom pixel:

window.parent.postMessage({
  name: 'init',
  data: init,
}, '*');

analytics.subscribe("all_standard_events", event => {
  if (event.context?.window?.location?.href?.includes('/checkout')) {
    return;
  }
  window.parent.postMessage(event, '*');
});

This sends the events to the main window, where we listen for them in a script loaded into our app embed block:
window.addEventListener('message', handleEventMessage);

handleEventMessage processes the events for Facebook, GTM/GA4, and Bing by calling their pixel SDKs (all of which require access to the DOM).

Unfortunately sandboxing pixels is not practical in many cases. For instance GTM loads other scripts and custom HTML by attaching it to the DOM, and some events are automatically tracked like page_view which look at the URL of the current window. For app pixels they can't even load the scripts (no DOM access), for custom pixels they receive incorrect information for automatically collected events.

For the checkout pages, we literally have to copy out the event handlers from our app embed block and paste the code into a custom pixel, and then filter which events are being handled since app embed blocks can't be loaded on the checkout page (it appears).

Anyways, thanks! I do hope this results in a better API for analytics, with some kind of limited DOM access for these pixels (especially GTM).

[sillycube]

Hi,

I'm a bundle app developer and I have integrated with more than 15 cart drawers from various apps and themes.

There are a few things I want to mention. Theme or app developers may act as the event creator and consumer at the same time. They may not only act as a single role. If you define the theme or app developer to act as a role, this is not appropriate.

My use case is mostly related to adding a bundle to cart. Other bundle apps may have a similar workflow:

1. My bundle app adds a bundle to the cart
2. My bundle app emtis a refresh-cart event
3. The cart drawer listens to the refresh-cart event
4. The cart drawer refresh and open the cart drawer
5. (Optional) It'd be great if the cart drawer can return the result as Bool, so that I know the cart drawer is updated or not. When I dispatch an event, I can't get the returned result
6. If the cart drawer can't be updated, my app redirects customers to the cart page

Here are the event listeners and triggers defined by some themes. Your team might read these docs before:
https://roartheme.co/blogs/concept/javascript-events-for-developers

https://support.maestrooo.com/article/764-javascript-events-exposed-by-the-theme

[PaulNewton]

If you define the theme or app developer to act as a role, this is not appropriate.

How? The role of "app" doesn't mean not allowed to consume theme events.
In the context clues, for an event, an app being able to consume other events has nothing to do with the app clearly labeling an app is what dispatched/modified an event.

In the example the app is a provider of an app event role
The cart drawer opening would be a separate theme event role as it's managed by the app.
The app being a consumer doesn't mean the app has the role of theme.
If not an outright UI state variable.

Unifying cart-- drawer/popup/modal 's state indicators is needed though.

[sakshigupta1996]

Thanks for putting together this proposal. Standardizing storefront DOM event payloads is a huge step forward for improving interoperability between themes, apps, and analytics solutions. From the perspective of app developers which have intents that they also wish to publish for other interactions to latch on to

1. Wishlist-related event coverage
   Today, there are standardized events for product, cart, and search actions, but not for pre-purchase intent capture. Adding a few more standardized events in this category would improve coverage of the full shopper journey:

wishlist:add – fired when a product or variant is added to wishlist

wishlist:remove – fired when removed

wishlist:view – when the shopper views or opens the wishlist page

wishlist:share – when the wishlist is shared externally

These events should follow the same structure as the existing ones, with a payload that includes product, selectedVariant, and customer objects, and a context to identify the source (product page, collection page, or quick-view modal). Also we are happy to collaborate on this in anyway with the team at shopify - since we do hold a significant number of merchants (48K+) to test run these events for

2. Variant-level granularity
   shopper interactions happen at the product and variant level, Like a product seach/ view might just be at a product level, but we would love to have the event enriched with the variant details as well - to avoid making that extra call to the apis to get more of the product information. For events like cart:add, cart:update - selected variant also should be added on to the same list of properties

3. Customer context
   Another critical piece of information for engagement workflows is customer context. Events that originate from logged-in sessions could optionally include a customer object.

4. Contextual consistency
   The proposed context field is an excellent addition. It would be helpful to formalize a consistent shape for it, such as:

{
  "source": "collection" | "product" | "quickview" | "search",
  "template": "product-card" | "product-form" | "cart-drawer"
}

This would help event consumers understand where an interaction occurred without inferring it from URL or DOM structure. That distinction is often important for engagement apps that adapt UI behavior depending on context.

5. Balancing payload size and usefulness
   The goal of keeping payloads performant and lightweight is important, but the minimal set of identifiers currently proposed (like just product.id or variant.id) is not enough to eliminate redundant API requests. A middle ground would be to include a curated subset of key fields across product, variant, cart, and customer objects enough to cover the majority of app workflows without rendering full GraphQL responses in Liquid.
   Properties for product should include title, price at the minimum to help render the details for apps!

I was also curious if these events will be available only for newer themes or should we expect this consistency across all themes?
I also read that the event creation is mainly for theme developers, but i strongly believe app blocks and extensions also should have access to emit these events!

[ceri-waterscreative]

Wishlist is not a standard feature/event - so why should all sites have those events added?
This is about standard events.

Having a standard/method for dispatching events I can get behind though.

[PaulNewton]

This is about standard events.

wishlist seems far off, but lets be real we don't even have a actual list of what those actually are yet , so spitball usecases are kinda fair game.

[sakshigupta1996]

The addition of wishlist is one such intent that we are not able to publish consistently across themes and causes pain to the merchant to customise and understand different touchpoints in a shoppers journey - What i am proposing is a exhaustive list that can come to standardise these for merchants! Leaving a review is also not a default functionality but coming to it merchant would like to give a discount on the next purchase if someone leaves a review - similarly merchant would want to engage shoppers who have not yet made a decision to buy and wishlisted items - having the option to emit these events wih a common standard opens a lot of doors for these flows to be customised and understood further

[si-khooks]

You mentioned analytics, but this is explicitly duplicating some events that already are created by analytics. That's why I really think the analytics events should just be made available to the front-end. Why duplicate all of this work? I don't think it's adding interoperability if we end up with two sets of events and event APIs depending on whether you're inside a pixel or the theme. There should be a single consistent event interface, even if the event delivery method varies (DOM events vs Pixel SDK).

[ceri-waterscreative]

Eh disagree, the two have very different purposes so the data required is going to vary.
I.e. we don't need attribution data in storefront payloads.