Eventos

Los eventos te permiten ejecutar código cuando algo sucede en el carrito. Viven bajo window.aftersell.cart.events. Suscribirse es una llamada de configuración, así que es seguro al principio de tu script, sin necesidad de esperar a ready().

Eventos disponibles

Evento	Payload	Se dispara cuando
`cart_loaded`	`AftersellCart`	El carrito se carga, una vez por página.
`cart_updated`	`AftersellCart`	El contenido del carrito cambia, después de la primera carga.
`item_added`	`{ item }`	Una nueva línea aparece en el carrito.
`item_removed`	`{ item }`	Una línea desaparece del carrito.
`cart_opened`	Ninguno	El drawer se abre.
`cart_closed`	Ninguno	El drawer se cierra.
`checkout`	Ninguno	Se hace clic en el botón de checkout.

Suscripción

events.on(event, handler) registra un handler y devuelve una función que cancela su suscripción:

const off = window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log('Cart total is now', state.totalPrice);
});

// later, to stop listening:
off();

events.once(event, handler): se dispara una vez y luego cancela su propia suscripción.
events.off(event, handler): elimina un handler específico.

Un handler que lanza una excepción queda aislado y se registra en la consola; los demás handlers siguen ejecutándose.

Las dos reglas

Casi todos los bugs de eventos se remontan a una de estas.

No cambies el carrito desde `cart_updated` sin una protección

Cambiar el carrito dentro de un handler de cart_updated dispara cart_updated de nuevo. Si ese handler cambia el carrito otra vez, tienes un bucle infinito. El comprador ve su carrito agitarse mientras la página martillea a Shopify.

Nunca llames a una acción incondicionalmente desde cart_updated o cart_loaded. Protégela con una verificación del estado que estás a punto de crear, para que la segunda pasada no haga nada.

// ❌ Loops forever: every add triggers an update, which triggers another add.
window.aftersell.cart.events.on('cart_updated', (state) => {
  window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
});

// ✅ Guarded: once the gift is present, the condition is false and it stops.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
  if (state.totalPrice >= 5000 && !hasGift) {
    window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  }
});

El carrito sí te da una red de seguridad: una actualización que produce un carrito idéntico no emite nada, así que un refetch que no cambia nada no reiniciará el ciclo. Eso te protege de bucles accidentales sin efecto. No te protege de un handler que genuinamente cambia el carrito cada vez.

Trata el payload como de solo lectura

Todos los handlers de un evento reciben el mismo objeto. Mutarlo cambia lo que ven los handlers posteriores al tuyo, incluidos los handlers que pertenecen a otras apps de la tienda.

// ❌ Corrupts the payload for every later handler.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items = state.items.filter((line) => line.finalLinePrice > 0);
});

// ✅ Copy first.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const paidItems = state.items.filter((line) => line.finalLinePrice > 0);
});

Para cambiar realmente el carrito, usa una acción. Para cambiar cómo se renderizan las líneas, usa registerLineTransform.

cart_loaded

Se dispara una vez, cuando el carrito se carga por primera vez en la página. El payload es el objeto cart completo.

window.aftersell.cart.events.on('cart_loaded', (state) => {
  console.log('Page loaded with', state.itemCount, 'items');
});

Úsalo para: cualquier cosa que necesite ejecutarse contra el estado inicial del carrito, como reconciliar un regalo gratis, inicializar un widget o reportar el contenido del carrito a analíticas al cargar la página. cart_loaded se reproduce para los suscriptores tardíos. Si te suscribes después de que el carrito ya se cargó, tu handler es llamado inmediatamente con el carrito actual. El orden de suscripción nunca importa, así que no tienes que preocuparte de si tu script le ganó al carrito.

La lógica que tiene que ser correcta tanto al cargar la página como en cada cambio posterior debe suscribirse a ambos cart_loaded y cart_updated con la misma función. Ese es el patrón estándar para “mantener X sincronizado con el carrito”.

cart_updated

Se dispara cada vez que el contenido del carrito cambia después de la primera carga, ya sea desde el drawer, desde tus propias acciones, desde el tema o desde otra app. El payload es el objeto cart completo.

window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#my-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});

Úsalo para: mantener sincronizado algo fuera del carrito, como un total personalizado, una barra de progreso, una insignia en el encabezado o un evento de analíticas en cada cambio. Una actualización que produce un carrito idéntico no emite nada. Volver a abrir el drawer, regresar de otra pestaña o un refetch que devuelve el mismo contenido no lo disparará.

Vuelve a leer las dos reglas antes de llamar a una acción aquí dentro.

item_added

Se dispara cuando una nueva línea aparece en el carrito. El payload es { item }, donde item es la línea del carrito.

window.aftersell.cart.events.on('item_added', (payload) => {
  myAnalytics.track('Added to cart', {
    id: payload.item.variantId,
    title: payload.item.title,
    quantity: payload.item.quantity,
  });
});

Úsalo para: el seguimiento de agregar al carrito en una herramienta de analíticas de terceros. Este es el uso más común del SDK. Consulta seguimiento de agregar al carrito. Dos cosas que debes saber sobre cómo se deriva:

Un cambio de cantidad no es un agregado. El carrito determina los agregados y las eliminaciones comparando líneas, no cantidades. Un comprador que sube una línea de 1 a 3 dispara cart_updated, no item_added. Si necesitas capturar también los aumentos de cantidad, compara contra el estado anterior en un handler de cart_updated.

Tampoco se dispara para artículos que ya estaban en el carrito cuando la página se cargó; esos llegan vía cart_loaded. Agregar varios productos distintos a la vez dispara el evento una vez por línea.

item_removed

Se dispara cuando una línea desaparece del carrito. El payload es { item }, la línea tal como estaba justo antes de desaparecer, así que aún puedes leer su key, variantId y title.

window.aftersell.cart.events.on('item_removed', (payload) => {
  console.log('Removed', payload.item.title);
});

Úsalo para: revertir algo que hiciste al agregar, como limpiar un flag, volver a mostrar una oferta que el comprador rechazó o reportar eliminaciones a analíticas. La misma salvedad que item_added: bajar una cantidad sin llegar a cero no es una eliminación.

cart_opened y cart_closed

Se disparan cuando el drawer se abre y se cierra. Sin payload.

window.aftersell.cart.events.on('cart_opened', () => {
  myAnalytics.track('Cart viewed');
});

window.aftersell.cart.events.on('cart_closed', () => {
  document.body.classList.remove('cart-is-open');
});

Úsalos para: seguimiento de vistas, pausar un video o carrusel detrás del drawer, alternar una clase en la página. Ninguno se dispara en la carga inicial de la página, solo en una apertura o cierre real.

checkout

Se dispara cuando el comprador hace clic en el botón de checkout, inmediatamente antes de que el navegador navegue. Sin payload.

window.aftersell.cart.events.on('checkout', () => {
  myAnalytics.track('Checkout started');
});

Úsalo para: seguimiento de intención de checkout.

No puedes cancelar el checkout desde este handler. El evento es una notificación, no una compuerta; la navegación ocurre sin importar lo que haga tu código. Mantén el handler rápido y síncrono: un await o una llamada de red lenta pueden no terminar antes de que la página se descargue. Usa navigator.sendBeacon para cualquier cosa que necesites enviar de forma confiable.

Escuchar desde fuera del SDK

Cada evento también se despacha como un CustomEvent del DOM en window, así que puedes escuchar sin tocar window.aftersell.cart. Eso es útil desde un archivo del tema, una app de terceros o un script que se carga independientemente del carrito.

Evento del bus	Evento del DOM
`cart_loaded`	`aftersell:cart:cart-loaded`
`cart_updated`	`aftersell:cart:cart-updated`
`item_added`	`aftersell:cart:item-added`
`item_removed`	`aftersell:cart:item-removed`
`cart_opened`	`aftersell:cart:cart-opened`
`cart_closed`	`aftersell:cart:cart-closed`
`checkout`	`aftersell:cart:checkout`

Ten cuidado con la nomenclatura: el bus usa snake_case, los eventos del DOM usan kebab-case detrás de un prefijo aftersell:cart:.

window.addEventListener('aftersell:cart:cart-updated', (event) => {
  console.log('Cart total is now', event.detail.totalPrice);
});

El payload llega en event.detail y coincide con el objeto cart. Los eventos se despachan en window, así que un listener en cualquier parte de la página los recibe. El carrito se renderiza en un shadow root, pero el límite del shadow nunca está en la ruta del evento. Cada despacho clona el payload, así que un listener que muta event.detail no puede afectar a nadie más, y un listener que lanza una excepción no puede interrumpir el SDK.

cart-loaded no se reproduce en el DOM. El bus reproduce cart_loaded para los suscriptores tardíos, pero esa ruta omite el despacho al DOM, así que un window.addEventListener('aftersell:cart:cart-loaded') registrado después de que el carrito ya se cargó nunca se disparará. Si el orden de carga de tu script no está garantizado, usa window.aftersell.cart.events.on('cart_loaded', …), que sí se reproduce, o escucha también aftersell:cart:cart-updated.

Eventos estándar de carrito de Shopify

Por separado, el carrito publica los eventos estándar de carrito de Shopify en document cada vez que cambia el carrito, para que el código del tema y otras apps puedan reaccionar a las mutaciones de Aftersell de la misma forma que reaccionan a las del tema:

Evento	Payload en la instancia del evento
`shopify:cart:lines-update`	`action: 'add' \| 'update' \| 'remove'`, `context: 'cart' \| 'product'`, `lines`
`shopify:cart:note-update`	`context: 'cart'`, `note`
`shopify:cart:discount-update`	`discountCodes: [{ code }]`

El payload no está en event.detail. detail solo lleva { source: 'aftersell' }, la etiqueta que el carrito usa para ignorar sus propios eventos en lugar de entrar en bucle. Todo lo de la tabla de arriba se asigna directamente al objeto del evento, así que lee event.action, no event.detail.action.

Cada evento también lleva una promise que Aftersell resuelve cuando la escritura subyacente se completa, siguiendo el estándar de Shopify: espérala con await, no la resuelvas tú. Estos se despachan en document y burbujean, así que un listener en window también los recibe.

Adónde ir después

Objeto cart: la forma completa de los payloads de arriba.
Acciones: cómo cambiar el carrito desde un handler.
Hooks: para cambiar cómo se renderiza el carrito, en lugar de reaccionar a él.
Casos de uso: seguimiento de analíticas, regalos gratis y otros ejemplos completos.

Primeros pasos

Página de inicio

Mejores prácticas

Ventas adicionales poscompra

Carrito

Ventas adicionales en el pago (Shopify Plus)

Página de agradecimiento

Ventas adicionales en la página de producto

Rokt Thanks

Estrategias

Analíticas y seguimiento

Integraciones

Aftersell MCP

Facturación y cuenta

Solución de problemas

Eventos disponibles

Suscripción

Las dos reglas

No cambies el carrito desde `cart_updated` sin una protección

Trata el payload como de solo lectura

cart_loaded

cart_updated

item_added

item_removed

cart_opened y cart_closed

checkout

Escuchar desde fuera del SDK

Eventos estándar de carrito de Shopify

Adónde ir después

​Eventos disponibles

​Suscripción

​Las dos reglas

​No cambies el carrito desde cart_updated sin una protección

​Trata el payload como de solo lectura

​cart_loaded

​cart_updated

​item_added

​item_removed

​cart_opened y cart_closed

​checkout

​Escuchar desde fuera del SDK

​Eventos estándar de carrito de Shopify

​Adónde ir después

Eventos disponibles

Suscripción

Las dos reglas

No cambies el carrito desde `cart_updated` sin una protección

Trata el payload como de solo lectura

cart_loaded

cart_updated

item_added

item_removed

cart_opened y cart_closed

checkout

Escuchar desde fuera del SDK

Eventos estándar de carrito de Shopify

Adónde ir después