> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usos comunes de la API de Upcart

> Aprende a aprovechar la API pública de Upcart con ejemplos prácticos para copiar y pegar.

<div id="how-the-api-pattern-works">
  ## Cómo funciona el patrón de la API
</div>

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?](/es/upcart/what_is_an_api) antes de sumergirte en los ejemplos siguientes.

***

<div id="where-to-add-your-scripts">
  ## Dónde agregar tus scripts
</div>

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`.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Una nota sobre callbacks heredados vs. modernos
</div>

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.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Ejemplo 1: Ocultar el botón fijo del carrito cuando el carrito está vacío
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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`.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Ejemplo 2: Registrar cuando se agrega un artículo al carrito
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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                       |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Ejemplo 3: Integrar con una app de analítica de terceros (p. ej. TripleWhale)
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Ejemplo 4: Abrir el carrito automáticamente después de agregar un producto
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Referencia rápida: Funciones de suscripción (API moderna)
</div>

| 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"` |

***

<div id="direct-action-functions">
  ## Funciones de acción directa
</div>

| 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](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Solución de problemas
</div>

* **¿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](/es/upcart/upcart_api_frequently_asked_questions) para más pasos de solución de problemas.