Häufige Anwendungsfälle der Upcart-API

So funktioniert das API-Muster

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?, bevor du dich in die Beispiele unten stürzt.

Wo du deine Skripte hinzufügst

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.

Ein Hinweis zu Legacy- vs. modernen Callbacks

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.

Beispiel 1: Den Sticky-Cart-Button ausblenden, wenn der Warenkorb leer ist

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

Beispiel 2: Protokollieren, wenn ein Artikel zum Warenkorb hinzugefügt wird

<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

Beispiel 3: Integration mit einer Drittanbieter-Analytics-App (z. B. TripleWhale)

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

Beispiel 4: Den Warenkorb automatisch öffnen, nachdem ein Produkt hinzugefügt wurde

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

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

Direkte Aktionsfunktionen

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.

Fehlerbehebung

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.

Erste Schritte

Warenkorb-Module

Warenkorb-Einstellungen

Sticky-Warenkorb-Button

Multicart

Anpassungen

Analytics

Integrationen & Kompatibilität

Abrechnung & Konto

Fehlerbehebung

Häufige Anwendungsfälle der Upcart-API

So funktioniert das API-Muster

Wo du deine Skripte hinzufügst

Ein Hinweis zu Legacy- vs. modernen Callbacks

Beispiel 1: Den Sticky-Cart-Button ausblenden, wenn der Warenkorb leer ist

Beispiel 2: Protokollieren, wenn ein Artikel zum Warenkorb hinzugefügt wird

Beispiel 3: Integration mit einer Drittanbieter-Analytics-App (z. B. TripleWhale)

Beispiel 4: Den Warenkorb automatisch öffnen, nachdem ein Produkt hinzugefügt wurde

Direkte Aktionsfunktionen

Fehlerbehebung

​So funktioniert das API-Muster

​Wo du deine Skripte hinzufügst

​Ein Hinweis zu Legacy- vs. modernen Callbacks

​Beispiel 1: Den Sticky-Cart-Button ausblenden, wenn der Warenkorb leer ist

​Beispiel 2: Protokollieren, wenn ein Artikel zum Warenkorb hinzugefügt wird

​Beispiel 3: Integration mit einer Drittanbieter-Analytics-App (z. B. TripleWhale)

​Beispiel 4: Den Warenkorb automatisch öffnen, nachdem ein Produkt hinzugefügt wurde

​Schnellreferenz: Subscribe-Funktionen (moderne API)

​Direkte Aktionsfunktionen

​Fehlerbehebung

So funktioniert das API-Muster

Wo du deine Skripte hinzufügst

Ein Hinweis zu Legacy- vs. modernen Callbacks

Beispiel 1: Den Sticky-Cart-Button ausblenden, wenn der Warenkorb leer ist

Beispiel 2: Protokollieren, wenn ein Artikel zum Warenkorb hinzugefügt wird

Beispiel 3: Integration mit einer Drittanbieter-Analytics-App (z. B. TripleWhale)

Beispiel 4: Den Warenkorb automatisch öffnen, nachdem ein Produkt hinzugefügt wurde

Schnellreferenz: Subscribe-Funktionen (moderne API)

Direkte Aktionsfunktionen

Fehlerbehebung