Usi comuni dell'API di Upcart

Come funziona il pattern dell’API

La maggior parte degli script dell’API di Upcart segue lo stesso semplice pattern: Ascolta un evento del carrello → Verifica una condizione → Esegui un’azione Ad esempio: “Quando il carrello si carica → controlla se è vuoto → nascondi il pulsante sticky.” 💡 Nuovo alle API? Inizia con Cos’è un’API? prima di passare agli esempi qui sotto.

Dove aggiungere i tuoi script

Tutti gli script qui sotto vanno in: Cart Editor → Settings → Custom HTML → Scripts (before load) Racchiudi ogni snippet in tag <script>...</script> e salva. Per testare, apri la console degli Strumenti per sviluppatori del tuo browser (F12) e cerca eventuali messaggi console.log.

Una nota sulle callback legacy e moderne

Upcart ha due modi per ascoltare gli eventi del carrello:

Stile	Esempio	Stato
Moderno (consigliato)	`upcartSubscribeAddedToCart(fn)`	Attuale
Legacy (deprecato)	`upcartOnAddToCart = fn`	Funziona ancora, registra un avviso in console

Tutti gli esempi qui sotto usano l’API moderna. Gli script esistenti che usano il vecchio stile continueranno a funzionare.

Esempio 1: nascondere il pulsante sticky del carrello quando il carrello è vuoto

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

Come funziona: upcartSubscribeCartLoaded viene attivato ogni volta che il carrello viene caricato. La callback riceve un event con un oggetto cart che contiene un array items. Sommiamo la quantity di ogni articolo per determinare se il carrello è vuoto. ⚠️ IMPORTANTE: event.cart NON ha una proprietà item_count. Devi calcolare il totale iterando event.cart.items.

Esempio 2: registrare quando un articolo viene aggiunto al carrello

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

Proprietà disponibili su event.item:

Proprietà	Descrizione
`event.item.title`	Titolo del prodotto
`event.item.quantityAdded`	Numero di unità aggiunte in questa azione
`event.item.quantity`	Quantità totale di questo articolo ora nel carrello
`event.item.variantId`	ID variante Shopify
`event.item.handle`	Handle del prodotto
`event.item.productId`	ID prodotto Shopify
`event.item.finalPrice`	Prezzo finale dopo gli sconti
`event.item.image`	URL dell’immagine del prodotto

Esempio 3: integrazione con un’app di analytics di terze parti (ad es. TripleWhale)

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

Nota: ogni app di terze parti è diversa. Verifica con il team di supporto della tua app il formato corretto degli eventi.

Esempio 4: aprire il carrello automaticamente dopo l’aggiunta di un prodotto

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

Nota: se “Open cart drawer on add to cart” è già abilitato in Cart Editor → Settings → Cart settings, non hai bisogno di questo script.

Funzione	Quando si attiva	La callback riceve
`upcartSubscribeCartLoaded(fn)`	I dati del carrello si caricano	`{ cart }` - cart ha `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Articolo aggiunto al carrello	`{ item }` - item ha `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	Il cart drawer si apre	`{}` (oggetto vuoto)
`upcartSubscribeCartClosed(fn)`	Il cart drawer si chiude	`{}` (oggetto vuoto)
`upcartSubscribeCartUpdated(fn)`	Il contenuto del carrello cambia	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Articolo rimosso	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Pulsante di checkout cliccato	`{ event }` - MouseEvent del browser
`upcartSubscribeUpsellsAddedToCart(fn)`	Articolo upsell aggiunto	`{ variant }` - ha `.id` e `.title`
`upcartSubscribeUpsellsRendered(fn)`	Gli upsell vengono renderizzati nel carrello	`{ item, element }` - item è il prodotto, element è il nodo DOM
`upcartSubscribeNotesTextChanged(fn)`	Note del carrello aggiornate	`{ newNotesText, oldNotesText }` - la nuova stringa delle note e quella precedente
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	Lo stato di un traguardo premio cambia	`{ numOfMilestonesCompleted, status }` - `status` è `"promotion"`, `"demotion"` o `"initial-state"`

Funzioni di azione diretta

Funzione	Cosa fa
`window.upcartOpenCart()`	Apre il cart drawer
`window.upcartCloseCart()`	Chiude il cart drawer
`window.upcartRefreshCart()`	Aggiorna i dati del carrello
`window.upcartGetCart()`	Restituisce l’oggetto carrello corrente
`window.upcartRegisterAddToCart()`	Registra l’add-to-cart per i page builder (Replo, PageFly, ecc.)
`window.upcartFormatMoney()`	Formatta un prezzo usando il formato valuta del tuo negozio

Per la documentazione completa dell’API, consulta la documentazione della Public API di Upcart.

Risoluzione dei problemi

Lo script non viene eseguito? Ricontrolla il posizionamento: dovrebbe essere in Scripts (before load), non after load.
Elemento non trovato? Assicurati che il selettore (ad es. #upCartStickyButton) corrisponda all’ID effettivo dell’elemento nel tuo carrello.
Qualcosa si è rotto? Commenta il tuo script aggiungendo // all’inizio di ogni riga, salva e aggiorna.
Sei ancora bloccato? Consulta le FAQ sull’API per ulteriori passaggi di risoluzione dei problemi.

Per iniziare

Moduli del carrello

Impostazioni del carrello

Pulsante carrello fisso

Multicart

Personalizzazioni

Analisi

Integrazioni e compatibilità

Fatturazione e account

Risoluzione dei problemi

Come funziona il pattern dell’API

Dove aggiungere i tuoi script

Una nota sulle callback legacy e moderne

Esempio 1: nascondere il pulsante sticky del carrello quando il carrello è vuoto

Esempio 2: registrare quando un articolo viene aggiunto al carrello

Esempio 3: integrazione con un’app di analytics di terze parti (ad es. TripleWhale)

Esempio 4: aprire il carrello automaticamente dopo l’aggiunta di un prodotto

Funzioni di azione diretta

Risoluzione dei problemi

​Come funziona il pattern dell’API

​Dove aggiungere i tuoi script

​Una nota sulle callback legacy e moderne

​Esempio 1: nascondere il pulsante sticky del carrello quando il carrello è vuoto

​Esempio 2: registrare quando un articolo viene aggiunto al carrello

​Esempio 3: integrazione con un’app di analytics di terze parti (ad es. TripleWhale)

​Esempio 4: aprire il carrello automaticamente dopo l’aggiunta di un prodotto

​Riferimento rapido: funzioni Subscribe (API moderna)

​Funzioni di azione diretta

​Risoluzione dei problemi

Come funziona il pattern dell’API

Dove aggiungere i tuoi script

Una nota sulle callback legacy e moderne

Esempio 1: nascondere il pulsante sticky del carrello quando il carrello è vuoto

Esempio 2: registrare quando un articolo viene aggiunto al carrello

Esempio 3: integrazione con un’app di analytics di terze parti (ad es. TripleWhale)

Esempio 4: aprire il carrello automaticamente dopo l’aggiunta di un prodotto

Riferimento rapido: funzioni Subscribe (API moderna)

Funzioni di azione diretta

Risoluzione dei problemi