Visión general

El Cart SDK es una API de JavaScript para el Aftersell Cart en tu tienda. Te permite cambiar cómo se comporta el carrito, reaccionar a lo que hacen los compradores y leer o cambiar el contenido del carrito desde código. Ejecutas código del SDK mediante Scripts personalizados, o mediante el modo React de un bloque Custom code para un bloque que renderiza su propia UI.

Mucho de lo que los comerciantes le piden al SDK ya es una configuración. Antes de escribir un script, verifica si un bloque del carrito, las condiciones por mercado/país/moneda o una configuración del carrito ya lo hacen. Esos siguen funcionando a través de rediseños del carrito, y tu script puede que no.

El punto de entrada global

Todo cuelga de un solo global:

window.aftersell.cart

Todos los snippets de estos docs escriben window.aftersell.cart completo, así que cualquiera de ellos funciona por sí solo cuando lo pegas. Crear un alias una vez (const cart = window.aftersell.cart;) y usar cart a partir de entonces también es perfectamente válido, y seguro incluso antes de que el carrito se cargue. Solo recuerda incluir esa línea si acortas un snippet, ya que un cart suelto por sí solo lanza cart is not defined.

Cuatro partes hacen el trabajo:

Configure

Establece cómo se comporta el carrito: cuándo se abre el drawer, cómo se formatea el dinero, si Aftersell intercepta el agregar al carrito.

Events

Reacciona a lo que sucede: el carrito se cargó, se agregó un artículo, el drawer se abrió, se hizo clic en el checkout.

Actions

Lee y cambia el carrito: ábrelo, agrega un artículo, actualiza una cantidad, lee el estado actual.

Hooks

Cambia cómo funciona el carrito en sí: oculta o reetiqueta líneas, reordénalas, adjunta datos extra, controla el agregar al carrito.

Si un script tuyo dejó de dispararse al agregar al carrito, empieza por Intercepción de agregar al carrito. Explica por qué Aftersell toma el control del agregado, y todas las formas de excluir un formulario.

Más tres miembros menores:

Miembro	Para qué sirve
`ready()`	Una Promise que se resuelve una vez que el carrito se ha cargado por primera vez.
`context`	Contexto del comprador renderizado por el servidor, legible de forma síncrona.
`shadowRoot`	El shadow root del carrito, para consultar elementos dentro del drawer.

¿Eventos, acciones o hooks?

Los tres son fáciles de confundir, y elegir el equivocado es la razón más común por la que un script no hace lo que su autor esperaba:

Quieres…	Usa	Ejemplo
Ejecutar código cuando algo sucede	Evento	Enviar un evento de analíticas cuando se agrega un artículo.
Cambiar lo que hay en el carrito	Acción	Agregar un regalo gratis una vez que el total supera $50.
Cambiar cómo funciona o se renderiza el carrito	Hook	Ocultar las líneas de regalo gratis del drawer.

La distinción que más importa: una acción cambia el carrito real del comprador (y su total), mientras que un hook solo cambia lo que se renderiza. Ocultar una línea con un hook la deja en el carrito y en el total; eliminarla con una acción la saca de verdad.

Cómo y cuándo se carga

El carrito se carga en dos etapas, y el SDK está construido para que no tengas que pensar en el orden:

Un pequeño stub crea window.aftersell.cart inmediatamente, así que siempre está ahí.
El SDK completo se carga poco después y toma el control, actualizando el stub en su lugar, así que una referencia que capturaste antes sigue funcionando.

Eso te da dos categorías de llamada:

Llamadas de configuración: seguras de inmediato

configure(...), events.on(...) y cada llamada hooks.register*. Se almacenan en búfer antes del arranque y se reproducen en orden una vez que el SDK se carga. Ponlas al principio de tu script.

Acciones: espera a ready()

Todo lo que está bajo actions.*. Ejecútalas dentro de ready() o de un handler de eventos. Llamadas demasiado pronto, advierten en la consola y no hacen nada, de forma segura: las asíncronas aún se resuelven, así que una cadena .then() no se romperá.

// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

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

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});

ready()

ready() devuelve una Promise que se resuelve una vez que la primera carga del carrito se asienta. Se resuelve tanto en fallo como en éxito, así que un comprador con una conexión inestable nunca deja tu script colgado. Verifica si getCart() es null en lugar de asumir que llegó un carrito. Llamar a ready() después de que el carrito ya se cargó se resuelve inmediatamente, así que es seguro usarla como una compuerta general de “el carrito ya existe” en cualquier parte de tu código.

No necesitas ready() dentro de un handler de eventos. Para cuando cart_loaded, cart_updated o item_added se dispara, el carrito está cargado y es seguro llamar a las acciones.

context

window.aftersell.cart.context contiene datos del comprador renderizados por el servidor, legibles de forma síncrona, sin necesidad de ready(). Úsalo para ramificaciones por mercado o país que deben ocurrir antes de que el carrito se cargue.

Campo	Descripción	Disponible antes del arranque
`shopify_market`	El mercado de Shopify del comprador.	Sí
`customer_country`	Código de país de dos letras.	Sí
`customer_currency`	Código de moneda activo.	Sí
`money_format`	El formato de dinero de Shopify de la tienda.	Sí
`backend_url`	Host directo del backend, usado como respaldo cuando el app proxy no está configurado.	Sí
`storefront_access_token`	Token para llamadas a la Storefront API.	No: se agrega cuando el carrito arranca

storefront_access_token es el único campo de context que el servidor no renderiza en cart.context. Se agrega a context cuando el carrito arranca, así que leerlo al principio de tu script devuelve undefined. Espera primero a window.aftersell.cart.ready().

if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}

Para mostrar configuraciones de bloque diferentes por mercado, país o moneda, usa las condiciones en el editor del carrito en su lugar. No se requiere script. La UI completa de Conditions está disponible hoy en Rewards.

shadowRoot

El carrito se renderiza dentro de un shadow root, así que document.querySelector no puede ver nada dentro del drawer. Para alcanzar un elemento en el carrito, consulta el shadow root:

const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');

Apunta a las mismas clases públicas cart-external-* que usa Custom CSS. Esos son los asideros soportados. Las gemelas cart-internal-* son la fontanería propia del carrito, así que consulta las externas en su lugar.

Recurre al shadow root solo cuando ningún bloque, configuración o hook haga el trabajo. Un hook sobrevive a un rediseño del carrito; una consulta al DOM es un problema de mantenimiento de tu código.

El shadow root solo está presente una vez que el carrito ha arrancado, así que léelo dentro de ready() o de un handler de eventos en lugar de al principio de tu script.

Depuración

Un script roto nunca debe tumbar el agregar al carrito ni el drawer, así que el SDK contiene los fallos en lugar de dejar que se propaguen. Dónde aflora un fallo depende de qué se rompió:

Qué falló	Dónde aparece
Tu script lanzó una excepción en el nivel superior	`console.error`, nombrando la línea y lo que nunca se ejecutó
Un handler de eventos lanzó una excepción	`console.error`; los demás handlers siguen ejecutándose
Un hook lanzó una excepción	Silencioso. Va al canal de depuración de abajo
Una acción se ejecutó antes de que el carrito se cargara	`console.warn`; la llamada no hace nada

Cuando tu script lanza una excepción

Un script personalizado se detiene en el primer error, así que cada configure, events.on y hooks.register* debajo de esa línea nunca se ejecuta. El carrito lo dice explícitamente:

[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.

Ese es el mensaje que debes buscar cuando un handler que definitivamente registraste nunca se dispara: probablemente nunca se alcanzó. El número de línea es la instrucción de nivel superior donde la ejecución se detuvo, no la función interna que lanzó la excepción, y se omite en lugar de adivinarse si el stack del navegador no es utilizable. Tus scripts también se ejecutan bajo sus propios nombres de archivo, así que aparecen como aftersell-cart-init.js y aftersell-cart-cart-update.js en DevTools. Puedes abrirlos desde el panel Sources y establecer breakpoints como en cualquier otro archivo.

El canal de depuración

Los fallos de hooks se mantienen deliberadamente fuera de la consola para que los compradores nunca los vean. En su lugar van aquí:

// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));

Adónde ir después

Configure

Cada opción, con un ejemplo cada una.

Events

Cada evento, cuándo se dispara y qué no hacer en un handler.

Actions

Cada acción, con un snippet cada una.

Hooks

Cada hook, y cómo se componen los registros.

Objeto cart

La forma del carrito y sus líneas.

Casos de uso

Soluciones completas y ejecutables a solicitudes comunes.

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

El punto de entrada global

Configure

Events

Actions

Hooks

¿Eventos, acciones o hooks?

Cómo y cuándo se carga

Llamadas de configuración: seguras de inmediato

Acciones: espera a ready()

ready()

context

shadowRoot

Depuración

Cuando tu script lanza una excepción

El canal de depuración

Adónde ir después

Configure

Events

Actions

Hooks

Objeto cart

Casos de uso

​El punto de entrada global

Configure

Events

Actions

Hooks

​¿Eventos, acciones o hooks?

​Cómo y cuándo se carga

Llamadas de configuración: seguras de inmediato

Acciones: espera a ready()

​ready()

​context

​shadowRoot

​Depuración

​Cuando tu script lanza una excepción

​El canal de depuración

​Adónde ir después

Configure

Events

Actions

Hooks

Objeto cart

Casos de uso

El punto de entrada global

¿Eventos, acciones o hooks?

Cómo y cuándo se carga

ready()

context

shadowRoot

Depuración

Cuando tu script lanza una excepción

El canal de depuración

Adónde ir después