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

# Utilisations courantes de l'API Upcart

> Découvrez comment exploiter l'API publique d'Upcart avec des exemples pratiques à copier-coller.

<div id="how-the-api-pattern-works">
  ## Comment fonctionne le schéma de l'API
</div>

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 ?](/fr/upcart/what_is_an_api) avant de vous plonger dans les exemples ci-dessous.

***

<div id="where-to-add-your-scripts">
  ## Où ajouter vos scripts
</div>

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

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## Remarque sur les callbacks hérités et modernes
</div>

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.

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## Exemple 1 : Masquer le bouton de panier fixe lorsque le panier est vide
</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>
```

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

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## Exemple 2 : Journaliser l'ajout d'un article au panier
</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>
```

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

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## Exemple 3 : Intégration avec une application d'analytique tierce (par ex. 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>
```

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

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## Exemple 4 : Ouvrir automatiquement le panier après l'ajout d'un produit
</div>

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

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## Référence rapide : fonctions d'abonnement (API moderne)
</div>

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

***

<div id="direct-action-functions">
  ## Fonctions d'action directe
</div>

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

***

<div id="troubleshooting">
  ## Dépannage
</div>

* **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](/fr/upcart/upcart_api_frequently_asked_questions) pour plus d'étapes de dépannage.