Usos comunes de la API de Upcart

Cómo funciona el patrón de la API

La mayoría de los scripts de la API de Upcart siguen el mismo patrón simple: Escuchar un evento del carrito → Comprobar una condición → Ejecutar una acción Por ejemplo: “Cuando se carga el carrito → comprueba si está vacío → oculta el botón fijo.” 💡 ¿Nuevo en las APIs? Empieza con ¿Qué es una API? antes de sumergirte en los ejemplos siguientes.

Dónde agregar tus scripts

Todos los scripts a continuación van en: Cart Editor → Settings → Custom HTML → Scripts (before load) Envuelve cada fragmento en etiquetas <script>...</script> y guarda. Para probar, abre la consola de las Dev Tools de tu navegador (F12) y busca cualquier mensaje de console.log.

Una nota sobre callbacks heredados vs. modernos

Upcart tiene dos formas de escuchar los eventos del carrito:

Estilo	Ejemplo	Estado
Moderno (recomendado)	`upcartSubscribeAddedToCart(fn)`	Actual
Heredado (obsoleto)	`upcartOnAddToCart = fn`	Sigue funcionando, registra una advertencia en la consola

Todos los ejemplos a continuación usan la API moderna. Los scripts existentes que usan el estilo antiguo seguirán funcionando.

Ejemplo 1: Ocultar el botón fijo del carrito cuando el carrito está vacío

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

Cómo funciona: upcartSubscribeCartLoaded se dispara cada vez que se carga el carrito. El callback recibe un event con un objeto cart que contiene un arreglo items. Sumamos la quantity de cada artículo para determinar si el carrito está vacío. ⚠️ IMPORTANTE: event.cart NO tiene una propiedad item_count. Debes calcular el total iterando event.cart.items.

Ejemplo 2: Registrar cuando se agrega un artículo al carrito

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

Propiedades disponibles en event.item:

Propiedad	Descripción
`event.item.title`	Título del producto
`event.item.quantityAdded`	Número de unidades agregadas en esta acción
`event.item.quantity`	Cantidad total de este artículo ahora en el carrito
`event.item.variantId`	ID de la variante de Shopify
`event.item.handle`	Handle del producto
`event.item.productId`	ID del producto de Shopify
`event.item.finalPrice`	Precio final después de descuentos
`event.item.image`	URL de la imagen del producto

Ejemplo 3: Integrar con una app de analítica de terceros (p. ej. TripleWhale)

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

Nota: Cada app de terceros es diferente. Consulta con el equipo de soporte de tu app cuál es el formato de evento correcto.

Ejemplo 4: Abrir el carrito automáticamente después de agregar un producto

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

Nota: Si “Open cart drawer on add to cart” ya está activado en Cart Editor → Settings → Cart settings, no necesitas este script.

Función	Cuándo se dispara	El callback recibe
`upcartSubscribeCartLoaded(fn)`	Se cargan los datos del carrito	`{ cart }` - cart tiene `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Se agrega un artículo al carrito	`{ item }` - item tiene `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	Se abre el cajón del carrito	`{}` (objeto vacío)
`upcartSubscribeCartClosed(fn)`	Se cierra el cajón del carrito	`{}` (objeto vacío)
`upcartSubscribeCartUpdated(fn)`	Cambia el contenido del carrito	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Se elimina un artículo	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Se hace clic en el botón de pago	`{ event }` - MouseEvent del navegador
`upcartSubscribeUpsellsAddedToCart(fn)`	Se agrega un artículo de upsell	`{ variant }` - tiene `.id` y `.title`
`upcartSubscribeUpsellsRendered(fn)`	Los upsells se renderizan en el carrito	`{ item, element }` - item es el producto, element es el nodo del DOM
`upcartSubscribeNotesTextChanged(fn)`	Se actualizan las notas del carrito	`{ newNotesText, oldNotesText }` - la nueva cadena de notas y la anterior
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	Cambia el estado de un hito de recompensa	`{ numOfMilestonesCompleted, status }` - `status` es `"promotion"`, `"demotion"` o `"initial-state"`

Funciones de acción directa

Función	Qué hace
`window.upcartOpenCart()`	Abre el cajón del carrito
`window.upcartCloseCart()`	Cierra el cajón del carrito
`window.upcartRefreshCart()`	Actualiza los datos del carrito
`window.upcartGetCart()`	Devuelve el objeto actual del carrito
`window.upcartRegisterAddToCart()`	Registra el agregar al carrito para constructores de páginas (Replo, PageFly, etc.)
`window.upcartFormatMoney()`	Formatea un precio usando el formato de moneda de tu tienda

Para la documentación completa de la API, consulta la Documentación de la API pública de Upcart.

Solución de problemas

¿El script no se ejecuta? Verifica de nuevo la ubicación: debe estar en Scripts (before load), no después de la carga.
¿No se encuentra el elemento? Asegúrate de que el selector (p. ej. #upCartStickyButton) coincida con el ID real del elemento en tu carrito.
¿Algo se rompió? Comenta tu script agregando // al inicio de cada línea, guarda y actualiza.
¿Sigues atascado? Consulta las Preguntas frecuentes sobre la API para más pasos de solución de problemas.

Getting Started

Cart Modules

Cart Settings

Sticky Cart Button

Multicart

Customizations

Analytics

Integrations & Compatibility

Billing & Account

Troubleshooting

Cómo funciona el patrón de la API

Dónde agregar tus scripts

Una nota sobre callbacks heredados vs. modernos

Ejemplo 1: Ocultar el botón fijo del carrito cuando el carrito está vacío

Ejemplo 2: Registrar cuando se agrega un artículo al carrito

Ejemplo 3: Integrar con una app de analítica de terceros (p. ej. TripleWhale)

Ejemplo 4: Abrir el carrito automáticamente después de agregar un producto

Funciones de acción directa

Solución de problemas

​Cómo funciona el patrón de la API

​Dónde agregar tus scripts

​Una nota sobre callbacks heredados vs. modernos

​Ejemplo 1: Ocultar el botón fijo del carrito cuando el carrito está vacío

​Ejemplo 2: Registrar cuando se agrega un artículo al carrito

​Ejemplo 3: Integrar con una app de analítica de terceros (p. ej. TripleWhale)

​Ejemplo 4: Abrir el carrito automáticamente después de agregar un producto

​Referencia rápida: Funciones de suscripción (API moderna)

​Funciones de acción directa

​Solución de problemas

Cómo funciona el patrón de la API

Dónde agregar tus scripts

Una nota sobre callbacks heredados vs. modernos

Ejemplo 1: Ocultar el botón fijo del carrito cuando el carrito está vacío

Ejemplo 2: Registrar cuando se agrega un artículo al carrito

Ejemplo 3: Integrar con una app de analítica de terceros (p. ej. TripleWhale)

Ejemplo 4: Abrir el carrito automáticamente después de agregar un producto

Referencia rápida: Funciones de suscripción (API moderna)

Funciones de acción directa

Solución de problemas