Utilisations courantes de l'API Upcart

Comment fonctionne le schéma de l’API

La plupart des scripts de l’API Upcart suivent le même schéma simple : Écouter un événement de panier → Vérifier une condition → Effectuer une action Par exemple : « Quand le panier se charge → vérifier s’il est vide → masquer le bouton fixe. » 💡 Nouveau avec les API ? Commencez par Qu’est-ce qu’une API ? avant de vous plonger dans les exemples ci-dessous.

Où ajouter vos scripts

Tous les scripts ci-dessous se placent dans : Cart Editor → Settings → Custom HTML → Scripts (before load) Encadrez chaque extrait de balises <script>...</script> et enregistrez. Pour tester, ouvrez la console des outils de développement de votre navigateur (F12) et recherchez les messages console.log.

Remarque sur les callbacks hérités et modernes

Upcart propose deux façons d’écouter les événements de panier :

Style	Exemple	Statut
Moderne (recommandé)	`upcartSubscribeAddedToCart(fn)`	Actuel
Hérité (obsolète)	`upcartOnAddToCart = fn`	Fonctionne encore, affiche un avertissement dans la console

Tous les exemples ci-dessous utilisent l’API moderne. Les scripts existants utilisant l’ancien style continueront de fonctionner.

Exemple 1 : Masquer le bouton de panier fixe lorsque le panier est vide

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

Comment ça fonctionne : upcartSubscribeCartLoaded se déclenche à chaque chargement du panier. Le callback reçoit un event avec un objet cart contenant un tableau items. Nous additionnons la quantity de chaque article pour déterminer si le panier est vide. ⚠️ IMPORTANT : event.cart ne possède PAS de propriété item_count. Vous devez calculer le total en parcourant event.cart.items.

Exemple 2 : Journaliser l’ajout d’un article au panier

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

Propriétés disponibles sur event.item :

Propriété	Description
`event.item.title`	Titre du produit
`event.item.quantityAdded`	Nombre d’unités ajoutées lors de cette action
`event.item.quantity`	Quantité totale de cet article désormais dans le panier
`event.item.variantId`	ID de variante Shopify
`event.item.handle`	Handle du produit
`event.item.productId`	ID de produit Shopify
`event.item.finalPrice`	Prix final après remises
`event.item.image`	URL de l’image du produit

Exemple 3 : Intégration avec une application d’analytique tierce (par ex. TripleWhale)

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

Remarque : Chaque application tierce est différente. Vérifiez auprès de l’équipe d’assistance de votre application le format d’événement correct.

Exemple 4 : Ouvrir automatiquement le panier après l’ajout d’un produit

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

Remarque : Si l’option « Open cart drawer on add to cart » est déjà activée dans Cart Editor → Settings → Cart settings, vous n’avez pas besoin de ce script.

Fonction	Quand elle se déclenche	Ce que reçoit le callback
`upcartSubscribeCartLoaded(fn)`	Les données du panier se chargent	`{ cart }` - cart possède `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Article ajouté au panier	`{ item }` - item possède `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	Le tiroir du panier s’ouvre	`{}` (objet vide)
`upcartSubscribeCartClosed(fn)`	Le tiroir du panier se ferme	`{}` (objet vide)
`upcartSubscribeCartUpdated(fn)`	Le contenu du panier change	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Article supprimé	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Clic sur le bouton de paiement	`{ event }` - MouseEvent du navigateur
`upcartSubscribeUpsellsAddedToCart(fn)`	Article d’upsell ajouté	`{ variant }` - possède `.id` et `.title`
`upcartSubscribeUpsellsRendered(fn)`	Les upsells s’affichent dans le panier	`{ item, element }` - item est le produit, element est le nœud DOM
`upcartSubscribeNotesTextChanged(fn)`	Notes du panier mises à jour	`{ newNotesText, oldNotesText }` - la nouvelle chaîne de notes et la précédente
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	Le statut d’un palier de récompense change	`{ numOfMilestonesCompleted, status }` - `status` vaut `"promotion"`, `"demotion"` ou `"initial-state"`

Fonctions d’action directe

Fonction	Ce qu’elle fait
`window.upcartOpenCart()`	Ouvre le tiroir du panier
`window.upcartCloseCart()`	Ferme le tiroir du panier
`window.upcartRefreshCart()`	Actualise les données du panier
`window.upcartGetCart()`	Renvoie l’objet panier actuel
`window.upcartRegisterAddToCart()`	Enregistre l’ajout au panier pour les constructeurs de pages (Replo, PageFly, etc.)
`window.upcartFormatMoney()`	Formate un prix selon le format monétaire de votre boutique

Pour la documentation complète de l’API, consultez la documentation de l’API publique d’Upcart.

Dépannage

Le script ne s’exécute pas ? Vérifiez son emplacement : il doit être dans Scripts (before load), pas après le chargement.
Élément introuvable ? Assurez-vous que le sélecteur (par ex. #upCartStickyButton) correspond à l’ID réel de l’élément dans votre panier.
Quelque chose s’est cassé ? Commentez votre script en ajoutant // au début de chaque ligne, enregistrez et actualisez.
Toujours bloqué ? Consultez la FAQ de l’API pour plus d’étapes de dépannage.

Getting Started

Cart Modules

Cart Settings

Sticky Cart Button

Multicart

Customizations

Analytics

Integrations & Compatibility

Billing & Account

Troubleshooting

Comment fonctionne le schéma de l’API

Où ajouter vos scripts

Remarque sur les callbacks hérités et modernes

Exemple 1 : Masquer le bouton de panier fixe lorsque le panier est vide

Exemple 2 : Journaliser l’ajout d’un article au panier

Exemple 3 : Intégration avec une application d’analytique tierce (par ex. TripleWhale)

Exemple 4 : Ouvrir automatiquement le panier après l’ajout d’un produit

Fonctions d’action directe

Dépannage

​Comment fonctionne le schéma de l’API

​Où ajouter vos scripts

​Remarque sur les callbacks hérités et modernes

​Exemple 1 : Masquer le bouton de panier fixe lorsque le panier est vide

​Exemple 2 : Journaliser l’ajout d’un article au panier

​Exemple 3 : Intégration avec une application d’analytique tierce (par ex. TripleWhale)

​Exemple 4 : Ouvrir automatiquement le panier après l’ajout d’un produit

​Référence rapide : fonctions d’abonnement (API moderne)

​Fonctions d’action directe

​Dépannage

Comment fonctionne le schéma de l’API

Où ajouter vos scripts

Remarque sur les callbacks hérités et modernes

Exemple 1 : Masquer le bouton de panier fixe lorsque le panier est vide

Exemple 2 : Journaliser l’ajout d’un article au panier

Exemple 3 : Intégration avec une application d’analytique tierce (par ex. TripleWhale)

Exemple 4 : Ouvrir automatiquement le panier après l’ajout d’un produit

Référence rapide : fonctions d’abonnement (API moderne)

Fonctions d’action directe

Dépannage