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

# Häufige Anwendungsfälle der Upcart-API

> Erfahre anhand praktischer Copy-Paste-Beispiele, wie du die Public API von Upcart einsetzt.

<div id="how-the-api-pattern-works">
  ## So funktioniert das API-Muster
</div>

Die meisten Upcart-API-Skripte folgen demselben einfachen Muster:

Auf ein Warenkorb-Ereignis lauschen → Eine Bedingung prüfen → Eine Aktion ausführen

Zum Beispiel: „Wenn der Warenkorb lädt → prüfen, ob er leer ist → den Sticky-Button ausblenden.“

💡 **Neu bei APIs?** Beginne mit [Was ist eine API?](/de/upcart/what_is_an_api), bevor du dich in die Beispiele unten stürzt.

***

<div id="where-to-add-your-scripts">
  ## Wo du deine Skripte hinzufügst
</div>

Alle folgenden Skripte gehören in:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

Umschließe jedes Snippet mit `<script>...</script>`-Tags und speichere. Öffne zum Testen die Dev-Tools-Konsole deines Browsers (`F12`) und suche nach `console.log`-Meldungen.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Ein Hinweis zu Legacy- vs. modernen Callbacks
</div>

Upcart bietet zwei Möglichkeiten, auf Warenkorb-Ereignisse zu lauschen:

| Stil               | Beispiel                         | Status                                                     |
| ------------------ | -------------------------------- | ---------------------------------------------------------- |
| Modern (empfohlen) | `upcartSubscribeAddedToCart(fn)` | Aktuell                                                    |
| Legacy (veraltet)  | `upcartOnAddToCart = fn`         | Funktioniert weiterhin, protokolliert eine Konsolenwarnung |

Alle folgenden Beispiele verwenden die moderne API. Bestehende Skripte im alten Stil funktionieren weiterhin.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Beispiel 1: Den Sticky-Cart-Button ausblenden, wenn der Warenkorb leer ist
</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>
```

**So funktioniert es:** `upcartSubscribeCartLoaded` wird jedes Mal ausgelöst, wenn der Warenkorb geladen wird. Der Callback erhält ein `event` mit einem `cart`-Objekt, das ein `items`-Array enthält. Wir summieren die `quantity` jedes Artikels, um festzustellen, ob der Warenkorb leer ist.

⚠️ **WICHTIG:** `event.cart` hat KEINE `item_count`-Eigenschaft. Du musst die Gesamtzahl durch Iterieren über `event.cart.items` berechnen.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Beispiel 2: Protokollieren, wenn ein Artikel zum Warenkorb hinzugefügt wird
</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>
```

**Auf `event.item` verfügbare Eigenschaften:**

| Eigenschaft                | Beschreibung                                                      |
| -------------------------- | ----------------------------------------------------------------- |
| `event.item.title`         | Produkttitel                                                      |
| `event.item.quantityAdded` | Anzahl der in dieser Aktion hinzugefügten Einheiten               |
| `event.item.quantity`      | Gesamtmenge dieses Artikels, die sich jetzt im Warenkorb befindet |
| `event.item.variantId`     | Shopify-Varianten-ID                                              |
| `event.item.handle`        | Produkt-Handle                                                    |
| `event.item.productId`     | Shopify-Produkt-ID                                                |
| `event.item.finalPrice`    | Endpreis nach Rabatten                                            |
| `event.item.image`         | URL des Produktbilds                                              |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Beispiel 3: Integration mit einer Drittanbieter-Analytics-App (z. B. 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>
```

> **Hinweis:** Jede Drittanbieter-App ist anders. Erkundige dich beim Support-Team deiner App nach dem korrekten Ereignisformat.

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Beispiel 4: Den Warenkorb automatisch öffnen, nachdem ein Produkt hinzugefügt wurde
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

> **Hinweis:** Wenn „Open cart drawer on add to cart“ bereits in **Cart Editor → Settings → Cart settings** aktiviert ist, brauchst du dieses Skript nicht.

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Schnellreferenz: Subscribe-Funktionen (moderne API)
</div>

| Funktion                                               | Wann sie ausgelöst wird                      | Der Callback erhält                                                                                      |
| ------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `upcartSubscribeCartLoaded(fn)`                        | Warenkorbdaten werden geladen                | `{ cart }` – cart hat `.items[]`, `.total`, `.currency`                                                  |
| `upcartSubscribeAddedToCart(fn)`                       | Artikel zum Warenkorb hinzugefügt            | `{ item }` – item hat `.title`, `.variantId`, `.quantityAdded`, `.quantity`                              |
| `upcartSubscribeCartOpened(fn)`                        | Cart Drawer öffnet sich                      | `{}` (leeres Objekt)                                                                                     |
| `upcartSubscribeCartClosed(fn)`                        | Cart Drawer schließt sich                    | `{}` (leeres Objekt)                                                                                     |
| `upcartSubscribeCartUpdated(fn)`                       | Warenkorbinhalt ändert sich                  | `{ cart }`                                                                                               |
| `upcartSubscribeItemRemoved(fn)`                       | Artikel entfernt                             | `{ item }`                                                                                               |
| `upcartSubscribeCheckoutClicked(fn)`                   | Checkout-Button geklickt                     | `{ event }` – Browser-MouseEvent                                                                         |
| `upcartSubscribeUpsellsAddedToCart(fn)`                | Upsell-Artikel hinzugefügt                   | `{ variant }` – hat `.id` und `.title`                                                                   |
| `upcartSubscribeUpsellsRendered(fn)`                   | Upsells werden im Warenkorb gerendert        | `{ item, element }` – item ist das Produkt, element ist der DOM-Knoten                                   |
| `upcartSubscribeNotesTextChanged(fn)`                  | Warenkorb-Notizen aktualisiert               | `{ newNotesText, oldNotesText }` – der neue Notiztext und der vorherige                                  |
| `upcartSubscribeRewardsMilestonesCompletedChanged(fn)` | Status eines Reward-Meilensteins ändert sich | `{ numOfMilestonesCompleted, status }` – `status` ist `"promotion"`, `"demotion"` oder `"initial-state"` |

***

<div id="direct-action-functions">
  ## Direkte Aktionsfunktionen
</div>

| Funktion                           | Was sie tut                                                    |
| ---------------------------------- | -------------------------------------------------------------- |
| `window.upcartOpenCart()`          | Öffnet den Cart Drawer                                         |
| `window.upcartCloseCart()`         | Schließt den Cart Drawer                                       |
| `window.upcartRefreshCart()`       | Aktualisiert die Warenkorbdaten                                |
| `window.upcartGetCart()`           | Gibt das aktuelle Warenkorb-Objekt zurück                      |
| `window.upcartRegisterAddToCart()` | Registriert Add-to-Cart für Page Builder (Replo, PageFly usw.) |
| `window.upcartFormatMoney()`       | Formatiert einen Preis mit dem Geldformat deines Stores        |

Die vollständige API-Dokumentation findest du in der [Upcart Public API Documentation](https://rokt.notion.site/upcart-public-api).

***

<div id="troubleshooting">
  ## Fehlerbehebung
</div>

* **Skript läuft nicht?** Überprüfe die Platzierung: Es sollte in *Scripts (before load)* stehen, nicht in after load.
* **Element nicht gefunden?** Stelle sicher, dass der Selektor (z. B. `#upCartStickyButton`) mit der tatsächlichen Element-ID in deinem Warenkorb übereinstimmt.
* **Etwas kaputt?** Kommentiere dein Skript aus, indem du `//` an den Anfang jeder Zeile setzt, speichere und aktualisiere.
* **Kommst du immer noch nicht weiter?** Weitere Schritte zur Fehlerbehebung findest du in den [API-FAQ](/de/upcart/upcart_api_frequently_asked_questions).