Events

The communication between the main page and the scripts is handled through events, ensuring a reactive and flexible integration where each component operates independently without direct calls.

• Events Dispatched by the Store / Checkout: When significant changes occur—such as an update to the shopping cart—the store or checkout dispatches events (e.g., cart:update) to notify scripts that a change has occurred.
• Events Dispatched by the Apps: Conversely, the scripts can emit events (like cart:validate) to report on the validity of the cart contents or to signal that additional actions might be required.

The listener always receives the current state at the time of the event. The listener signature is (state, event) => void, where event is the event name string. For nube.send, the second argument is optional: a function (state) => partialState; only the returned keys are merged into the current state.

This event-driven approach allows the application to respond in real-time to state changes, simplifying maintenance and enhancing scalability.

Events reference

Event	Dispatched by	Listen / Send	Description
page:loaded	store	Listen	Fired when the page is loaded and the SDK is ready to use.
checkout:ready	checkout	Listen	Fired when a new checkout page is loaded and ready.
checkout:success	checkout	Listen	Fired when checkout completes successfully.
config:set	app	Send	Set initial script configuration.
cart:update	store	Listen	Fired when the cart content changes.
cart:view	store	Listen	Fired when the user views the cart.
cart:validate	app	Send	Signal whether the cart content is valid (requires has_cart_validation: true).
cart:add	app	Send	Add an item to the cart.
cart:add:success	store	Listen	Fired when an item is successfully added; state.eventPayload has item context.
cart:add:fail	store	Listen	Fired when adding an item fails; state.eventPayload has context.
cart:remove	app	Send	Remove an item from the cart.
cart:remove:success	store	Listen	Fired when an item is successfully removed.
cart:remove:fail	store	Listen	Fired when removing an item fails.
order:update	checkout	Listen	Fired when the order is completed (success page).
order:add:tracking_statuses	app	Send	Add tracking statuses to the order.
coupon:add	app	Send	Add a coupon to the cart.
coupon:add:success	store	Listen	Fired when a coupon is successfully added.
coupon:add:fail	store	Listen	Fired when adding a coupon fails.
coupon:remove	app	Send	Remove a coupon from the cart.
coupon:remove:success	store	Listen	Fired when a coupon is successfully removed.
coupon:remove:fail	store	Listen	Fired when removing a coupon fails.
shipping:update	checkout	Listen	Fired when the shipping method changes.
shipping:select	app	Send	Change the selected shipping option.
shipping:select:success	checkout	Listen	Fired when a shipping option is selected successfully.
shipping:select:fail	checkout	Listen	Fired when selecting a shipping option fails.
shipping:update:label	app	Send	Update custom labels for shipping options.
customer:update	store	Listen	Fired when customer data changes.
payment:update	checkout	Listen	Fired when the payment method changes.
ui:slot:set	app	Send	Set or clear the content of a UI slot.
location:updated	store	Listen	Fired when the page or visible content changes.
quickbuy:open	store	Listen	Fired when the quick buy modal is opened; state.eventPayload has product data.
quickbuy:close	store	Listen	Fired when the quick buy modal is closed; state.eventPayload has product data.
custom:*:*	app / store	Listen & Send	Custom events (e.g. custom:modal:close). See Custom events .

Where events run

Some events are only available in checkout: cart:validate, coupon:add, coupon:remove, shipping:update, shipping:select, shipping:update:label, payment:update, order:add:tracking_statuses. Others are only available in storefront: cart:view, quickbuy:open, quickbuy:close. All other events work in both contexts (or depend on the page). Each restricted event is marked on its respective page.

Event groups

• Page & Lifecycle — page:loaded, checkout:ready, checkout:success, config:set, location:updated
• Cart — cart:update, cart:view, cart:validate, cart:add, cart:remove and their success/fail variants
• Order — order:update, order:add:tracking_statuses
• Coupon — coupon:add, coupon:remove and their success/fail variants
• Shipping — shipping:update, shipping:select, shipping:update:label and their success/fail variants
• Customer & Payment — customer:update, payment:update
• UI & Custom — ui:slot:set, quickbuy:open, quickbuy:close, custom events