Passer au contenu

Cette page a été traduite automatiquement et peut contenir des inexactitudes. Pour signaler une erreur de traduction, utilisez le module de commentaires en bas de la table des matières, à droite de la page.

Événements recommandés

Les événements recommandés reposent sur un framework qui envoie des événements personnalisés standardisés avec des schémas JSON définis. Lorsque vous envoyez un événement recommandé, Braze le valide par rapport à son schéma lors de l’ingestion et applique un traitement spécialisé, comme le calcul automatique de champs ou la gestion du panier, que les événements personnalisés génériques ne reçoivent pas. Pour certains ensembles d’événements sectoriels, Braze prend également en charge un traitement spécial, comme des déclencheurs basés sur l’action dédiés pour les Campaigns et les Canvas.

Événements eCommerce recommandés

Les événements eCommerce recommandés couvrent six étapes du parcours d’achat : product_viewed, cart_updated, checkout_started, order_placed, order_cancelled et order_refunded. Lorsque vous envoyez ces événements avec succès, Braze valide les données et les met à disposition d’un nombre croissant de fonctionnalités de la plateforme.

Ces fonctionnalités incluent des modèles de Canvas pour les flux de navigation abandonnée, de panier abandonné, de paiement abandonné et de confirmation de commande, le reporting eCommerce, ainsi que des champs calculés du profil utilisateur pour Chiffre d’affaires total, Total des commandes et Total des remboursements. Vous pouvez également créer des Segments grâce au filtrage imbriqué sur les propriétés des produits via les extensions de segments, personnaliser les messages de panier abandonné avec l’étiquette Liquid {% shopping_cart %}, et alimenter des fonctionnalités BrazeAI^TM comme les événements prédictifs, la prédiction du taux d’attrition et les recommandations d’articles, entre autres.

Comme ces événements suivent un schéma défini, chaque fonctionnalité prise en charge peut lire les données structurées sans mappage de propriétés personnalisé ni configuration spécifique de votre côté.

Important

L’ancien événement d’achat passe en mode maintenance. Les clients Braze existants peuvent continuer à utiliser les anciens événements d’achat. Ils continueront de fonctionner normalement, mais les nouvelles fonctionnalités seront désormais développées sur la base des événements recommandés pour le commerce électronique. Braze vous informera bien à l’avance avant qu’une date de fin de vie ne soit fixée. Les nouveaux clients Braze doivent utiliser les événements recommandés pour le commerce électronique, car les anciens événements d’achat ne seront pas disponibles.

Fonctionnement des événements eCommerce

Les événements eCommerce sont des événements personnalisés dont les noms et les schémas de propriétés sont prédéfinis. Vous les envoyez via le SDK de Braze, l’endpoint REST API /users/track ou l’ingestion de données cloud (CDI), et Braze valide chaque événement par rapport à son schéma lors de l’ingestion. Lorsque la validation réussit, Braze applique automatiquement un post-traitement propre à ce type d’événement, par exemple le calcul des champs de chiffre d’affaires et la gestion de l’état du panier sur les profils utilisateurs.

Remarque

Les importations CSV ne prennent pas en charge les événements eCommerce. Utilisez le SDK, /users/track ou CDI pour envoyer ces événements.

Les événements eCommerce fonctionnent partout où fonctionnent les autres événements personnalisés : déclencheurs et filtres pour les événements personnalisés effectués, reporting des événements personnalisés, etc. Leur validation de schéma débloque toutefois des fonctionnalités supplémentaires, notamment :

Les actions de déclenchement « Passe une commande » dans les Campaigns, les Canvas, les étapes de parcours d’action, les déclencheurs de messages in-app et la suppression des Content Cards
Les champs calculés eCommerce du profil utilisateur (Chiffre d’affaires total, Total des commandes, Total des remboursements)
La gestion de l’état du panier pour les flux de panier abandonné
Des données plus riches pour les fonctionnalités BrazeAI^TM comme les événements prédictifs, la prédiction du taux d’attrition et les recommandations d’articles

Vous pouvez également faire référence aux événements eCommerce par leur nom partout où la plateforme prend en charge les événements personnalisés. Par exemple, vous pouvez déclencher une campagne par événement avec des événements ecommerce.product_viewed, créer un Segment filtrant sur les événements ecommerce.checkout_started ou exporter des événements ecommerce.order_placed via Currents.

Nommage des événements

Les noms d’événements sont exacts, sensibles à la casse et délimités par des points. Utilisez toujours le format canonique. Si un nom d’événement ne correspond pas exactement à l’un des six noms canoniques, Braze le traite comme un événement personnalisé standard et aucun post-traitement eCommerce n’a lieu.

Vous ne pouvez ni personnaliser ni renommer les événements.

Correct : ecommerce.order_placed
Incorrect : order.placed, eCommerce_order_placed, Order_Placed

Schémas d’événements

Les six événements eCommerce recommandés correspondent aux étapes du parcours d’achat. Déclenchez chaque événement au moment où l’utilisateur effectue l’action correspondante.

Diagramme du parcours utilisateur à travers les six événements eCommerce recommandés : product_viewed, cart_updated, checkout_started, order_placed, order_cancelled et order_refunded.

Conseil

Les exemples des onglets suivants présentent le payload REST API de chaque événement.

Pour l’enregistrement côté client, ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started et ecommerce.order_placed utilisent les API d’événements eCommerce du SDK lorsqu’elles sont disponibles, tandis que ecommerce.order_cancelled et ecommerce.order_refunded utilisent logCustomEvent.

Les événements de remboursement et d’annulation sont généralement envoyés depuis votre serveur via la REST API de Braze, car ils dépendent le plus souvent de l’achèvement d’une logique côté serveur, comme votre flux de remboursement. Pour des exemples de déploiement propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Déclenchez cet événement lorsqu’un utilisateur consulte la page détaillée d’un produit. Cet événement est compatible avec les notifications de retour en stock et les notifications de baisse de prix des catalogues Braze.

Déploiement côté client

Utilisez les API d’événements eCommerce du SDK lorsqu’elles sont disponibles. Pour des exemples de déploiement propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Propriétés de l’événement

Nom de la propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit (par exemple, unité de gestion des stocks ou ID d’article).
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante du produit (par exemple, `shirt_medium_blue`).
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit pour plus de détails.
`price`	Float	Oui	Prix unitaire de la variante au moment de la consultation.
`currency`	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres (par exemple, `USD` ou `EUR`).
`source`	Chaîne de caractères	Oui	Source dont provient l’événement (par exemple, `web`, `ios` ou `android`).
`type`	Tableau de chaînes de caractères	Non	Obligatoire pour utiliser les fonctionnalités de déclencheurs de catalogue de Braze pour les alertes de retour en stock et de baisse de prix. Valeurs acceptées : `"price_drop"`, `"back_in_stock"`
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, `category` ou `brand`).

Exemple REST API

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Déclenchez cet événement chaque fois que le contenu du panier d’un utilisateur change.

Déploiement côté client

Vous pouvez envoyer cet événement de deux manières :

Remplacement complet du panier : Omettez action ou définissez action sur replace. Incluez l’ensemble des lignes d’articles dans products avec des quantités absolues (nombre total d’unités par variante dans le panier). Vous devez inclure total_value.
Mises à jour incrémentielles du panier : Définissez action sur add ou remove. Incluez uniquement les lignes d’articles qui ont changé. Chaque quantity correspond au nombre d’unités à ajouter ou à retirer, et non à la quantité totale dans le panier. Pour add, Braze augmente la quantité de la ligne ou ajoute une nouvelle ligne. Pour remove, Braze diminue la quantité de la ligne et supprime celle-ci lorsque la quantité atteint 0. total_value est facultatif pour add et remove.

Avertissement

Pour un panier donné, utilisez soit les mises à jour incrémentielles (add ou remove), soit le remplacement complet (sans action ou avec replace). Il est déconseillé de combiner les deux approches pour un même cart_id, car cela peut entraîner un état de panier incohérent dans Braze.

Pour déclencher des messages à partir de cet événement, utilisez le déclencheur Perform Cart Updated Event dans Canvas et dans les Campaigns. Ce déclencheur inclut un traitement spécial pour empêcher le panier de progresser dans l’entonnoir d’achat.

Conseil

Le panier crée sur le profil utilisateur un objet de mappage des paniers qui alimente l’étiquette Liquid {% shopping_cart %}. Le panier expire après 30 jours sans mise à jour. Si deux profils utilisateurs fusionnent, Braze conserve les deux paniers.

Propriétés de l’événement

Propriété	Type de données	Obligatoire	Description
`cart_id`	Chaîne de caractères	Oui	Identifiant unique du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur.
`action`	Chaîne de caractères	Non	`add` (augmente la quantité ou ajoute une ligne), `remove` (diminue la quantité ; la ligne est supprimée à `0`) ou `replace` (remplacement complet du panier, équivalent à l’omission de `action`).
`total_value`	Float	Conditionnel	Obligatoire lorsque `action` est omis ou vaut `replace`. Facultatif lorsque `action` vaut `add` ou `remove`.
`subtotal_value`	Float	Non	Sous-total du panier (après remise, avant taxes et frais de livraison).
`tax`	Float	Non	Total des taxes appliquées au panier.
`shipping`	Float	Non	Coût total de livraison du panier.
`currency`	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres.
`products`	Tableau	Oui	Lignes d’articles pour cette mise à jour. Pour un remplacement complet (sans `action` ou avec `replace`), incluez le panier complet avec des quantités absolues. Pour `add` ou `remove`, incluez uniquement les lignes modifiées ; consultez les propriétés du produit.
`source`	Chaîne de caractères	Oui	Source dont provient l’événement.
`metadata`	Objet	Non	Paires clé-valeur flexibles pour des données supplémentaires au niveau de l’événement.

Propriétés du produit (`products[]`)

Propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit.
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante.
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit.
`quantity`	Entier	Oui	Pour un remplacement complet (sans `action` ou avec `replace`), nombre d’unités de cette ligne dans le panier. Pour `add` ou `remove`, nombre d’unités à ajouter ou à retirer.
`price`	Float	Oui	Prix unitaire de la variante.
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, `color` ou `size`).

Déclenchez cet événement lorsque l’utilisateur lance le processus de paiement (par exemple, en sélectionnant « Paiement » ou en arrivant sur la page de paiement).

Déploiement côté client

Propriétés de l’événement

Propriété	Type	Obligatoire	Description
checkout_id	Chaîne de caractères	Oui	Identifiant unique de la session de paiement.
cart_id	Chaîne de caractères	Non	Identifiant du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur.
total_value	Float	Oui	Valeur monétaire totale du paiement.
subtotal_value	Float	Non	Sous-total (après remise, avant taxes et frais de livraison).
tax	Float	Non	Total des taxes appliquées au paiement.
shipping	Float	Non	Coût total de livraison.
currency	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres.
products	Tableau	Oui	Articles en cours de paiement. Consultez le sous-tableau des propriétés du produit.
source	Chaîne de caractères	Oui	Source dont provient l’événement.
metadata	Objet	Non	Paires clé-valeur flexibles. Sous-propriété reconnue : `checkout_url` (chaîne de caractères)

Propriétés du produit (`products[]`)

Propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit.
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante.
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit.
`quantity`	Entier	Oui	Nombre d’unités dans le panier.
`price`	Float	Oui	Prix unitaire de la variante.
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, couleur, taille).

Exemple REST API

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

Déclenchez cet événement lorsqu’une commande est finalisée avec succès ou que le paiement est confirmé.

Déploiement côté client

Important

Cet événement est la principale source de chiffre d’affaires. Il augmente total_revenue de la valeur indiquée dans total_value et augmente total_orders de 1 sur le profil utilisateur.

Propriétés de l’événement

Propriété	Type de données	Obligatoire	Description
`order_id`	Chaîne de caractères	Oui	Identifiant unique de la commande.
`cart_id`	Chaîne de caractères	Non	Identifiant du panier. Partagé entre les événements de panier, de paiement et de commande pour le mappage du panier de l’utilisateur.
`total_value`	Float	Oui	Valeur monétaire totale de la commande.
`subtotal_value`	Float	Non	Sous-total (après remise, avant taxes et frais de livraison).
`tax`	Float	Non	Total des taxes appliquées à la commande.
`shipping`	Float	Non	Coût total de livraison.
`currency`	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres.
`total_discounts`	Float	Non	Montant total des remises appliquées à la commande.
`discounts`	Tableau	Non	Liste détaillée des remises appliquées.
`products`	Tableau	Oui	Articles de la commande. Consultez le sous-tableau des propriétés du produit.
`source`	Chaîne de caractères	Oui	Source dont provient l’événement.
`metadata`	Objet	Non	Paires clé-valeur flexibles. Sous-propriété reconnue : `order_status_url` (chaîne de caractères)

Propriétés du produit (`products[]`)

Propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit.
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante.
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit.
`quantity`	Entier	Oui	Nombre d’unités dans le panier.
`price`	Float	Oui	Prix unitaire de la variante.
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, `color` ou `size`).

Exemple REST API

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Déclenchez cet événement lorsqu’une commande est annulée.

Déploiement côté client

Utilisez logCustomEvent. Pour des exemples de déploiement propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Important

Cet événement diminue total_orders de 1 sur le profil utilisateur. Il n’a aucun effet sur total_revenue ; utilisez order_refunded pour ajuster le chiffre d’affaires.

Propriétés de l’événement

Propriété	Type	Obligatoire	Description
`order_id`	Chaîne de caractères	Oui	Identifiant unique de la commande.
`total_value`	Float	Oui	Valeur monétaire totale de la commande annulée. Doit être ≥ 0 : envoyez le montant absolu ; Braze se charge de la décrémentation.
`subtotal_value`	Float	Non	Sous-total (après remise, avant taxes et frais de livraison).
`tax`	Float	Non	Total des taxes appliquées à la commande.
`shipping`	Float	Non	Coût total de livraison.
`currency`	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres.
`total_discounts`	Float	Non	Montant total des remises appliquées à la commande.
`discounts`	Tableau	Non	Liste détaillée des remises appliquées.
`cancel_reason`	Chaîne de caractères	Oui	Motif de l’annulation de la commande.
`products`	Tableau	Oui	Articles de la commande annulée. Consultez le sous-tableau des propriétés du produit.
`source`	Chaîne de caractères	Oui	Source dont provient l’événement.
`metadata`	Objet	Non	Paires clé-valeur flexibles. Sous-propriété reconnue : `order_status_url` (chaîne de caractères)

Propriétés du produit (`products[]`)

Propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit.
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante.
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit.
`quantity`	Entier	Oui	Nombre d’unités dans le panier.
`price`	Float	Oui	Prix unitaire de la variante.
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, `color` ou `size`).

Exemple REST API

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Déclenchez cet événement lorsqu’un remboursement total ou partiel est effectué.

Déploiement côté client

Utilisez logCustomEvent. Pour des exemples de déploiement propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Important

Cet événement diminue total_revenue de la valeur indiquée dans total_value et augmente total_refunds sur le profil utilisateur. Pour les remboursements partiels, définissez total_value sur le seul montant remboursé, et non sur le total de la commande initiale.

Propriétés de l’événement

Propriété	Type de données	Obligatoire	Description
`order_id`	Chaîne de caractères	Oui	Identifiant unique de la commande initiale.
`total_value`	Float	Oui	Valeur monétaire totale du remboursement. Doit être ≥ 0 : envoyez le montant absolu ; Braze se charge de l’incrémentation de total_refunds.
`currency`	Chaîne de caractères	Oui	Code ISO 4217 à trois lettres.
`total_discounts`	Float	Non	Montant total des remises appliquées initialement.
`discounts`	Tableau	Non	Liste détaillée des remises.
`products`	Tableau	Oui	Articles remboursés. Consultez le sous-tableau des propriétés du produit.
`source`	Chaîne de caractères	Oui	Source dont provient l’événement.
`metadata`	Objet	Non	Paires clé-valeur flexibles. Sous-propriété reconnue : `order_status_url` (chaîne de caractères).

Propriétés du produit (`products[]`)

Propriété	Type de données	Obligatoire	Description
`product_id`	Chaîne de caractères	Oui	Identifiant unique du produit.
`product_name`	Chaîne de caractères	Oui	Nom d’affichage du produit.
`variant_id`	Chaîne de caractères	Oui	Identifiant de la variante.
`image_url`	Chaîne de caractères	Non	URL de l’image du produit.
`product_url`	Chaîne de caractères	Non	URL de la page produit.
`quantity`	Entier	Oui	Nombre d’unités dans le panier.
`price`	Float	Oui	Prix unitaire de la variante.
`metadata`	Objet	Non	Paires clé-valeur flexibles (par exemple, `color` ou `size`).

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-04-29T10:05:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 189.99,
        "currency": "USD",
        "total_discounts": 0,
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11",
              "refund_reason": "size_mismatch"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-05-02T11:08:30Z",
      "properties": {
        "order_id": "ORD-20260428-7891",
        "total_value": 29.98,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "refund_method": "store_credit",
          "initiated_by": "customer"
        }
      }
    }
  ]
}

Post-traitement des événements eCommerce

Lorsque vous envoyez un événement eCommerce, Braze le valide par rapport au schéma attendu pour ce nom d’événement.

Le tableau suivant résume ce que Braze effectue automatiquement pour chaque événement lorsque la validation réussit. Pour savoir ce qui se passe en cas d’échec de la validation, consultez Validation et résolution des problèmes des événements.

Événement	Actions automatiques de Braze
`ecommerce.order_placed`	Augmente le Chiffre d’affaires total de `total_value` et le Total des commandes de 1 sur le profil utilisateur.
`ecommerce.order_cancelled`	Diminue le Total des commandes de 1.
`ecommerce.order_refunded`	Diminue le Chiffre d’affaires total de `total_value` et augmente la Valeur totale des remboursements.
`ecommerce.cart_updated`	Crée ou met à jour l’objet de mappage des paniers sur le profil utilisateur (payloads de panier complet, ou mises à jour incrémentielles avec `action` facultatif : `add`, `remove` ou `replace`). Le panier expire après 30 jours sans mise à jour.
`ecommerce.product_viewed`	Aucune modification du profil utilisateur. Disponible pour la segmentation, le déclenchement et les fonctionnalités BrazeAI^TM (comme les recommandations d’articles).
`ecommerce.checkout_started`	Aucune modification du profil utilisateur. Disponible pour la segmentation et le déclenchement (par exemple, les flux de paiement abandonné).

Important

Les valeurs dans une devise autre que l’USD sont automatiquement converties en USD selon le taux de change en vigueur à la date à laquelle l’événement est signalé. Si vous effectuez déjà vos rapports en USD, codez USD en dur comme devise pour éviter toute conversion involontaire.

Détails de mise en œuvre

Points de données et facturation

Les événements eCommerce ne consomment pas de points de données. Vous pouvez les enregistrer sans aucun impact sur votre utilisation des points de données.

Limite de taille des événements

Les propriétés d’événement envoyées à /users/track sont plafonnées à 102 400 octets (100 Ko) par événement. Pour les messages de campagnes et de Canvas déclenchés, les trigger_properties envoyées à /campaigns/trigger/send et à /canvas/trigger/send ont une limite par défaut plus stricte de 51 200 octets (50 Ko).

Selon les bonnes pratiques, envoyez uniquement les informations produit dont vous avez besoin pour déclencher, personnaliser ou attribuer l’événement. Stockez les détails produit plus complets (descriptions, listes complètes de variantes, inventaire ou images alternatives, par exemple) dans les catalogues Braze. Référencez ces détails par product_id ou variant_id lors de l’envoi de messages. Utilisez l’objet metadata de manière ciblée pour le contexte spécifique à la commande ou au produit que vos messages utiliseront.

Gestion des devises

Braze convertit automatiquement les montants en devises autres que l’USD en USD, en appliquant le taux de change en vigueur à la date à laquelle l’événement est signalé. C’est cette valeur convertie qui apparaît dans les indicateurs de chiffre d’affaires.

Conseil

Si vous travaillez uniquement en USD, codez en dur "currency": "USD" dans chaque événement pour éviter toute conversion inutile.

Champ source

La propriété source est une chaîne de caractères obligatoire qui identifie l’origine de l’événement, par exemple shopify, in-store POS ou custom_api. Elle vous permet de distinguer les sources d’intégration lorsque vous analysez des données dans les exportations Currents ou que vous résolvez des problèmes de validation.

Flexibilité des métadonnées

Les objets de métadonnées au niveau de l’événement et au niveau du produit acceptent tous deux des paires clé-valeur arbitraires. Vous pouvez donc ajouter des dimensions personnalisées sans modifier le schéma de base. Parmi les exemples courants, citons order_status_url, gift_wrapped, loyalty_points_earned ou warehouse_id. Ces propriétés sont disponibles pour la personnalisation Liquid, les exportations Currents et la segmentation via les extensions de segments.

Important

Les événements recommandés utilisent un schéma strict. Par conséquent, l’ajout de propriétés personnalisées au niveau supérieur des propriétés fera échouer la validation. Placez toutes les propriétés personnalisées dans l’objet metadata au niveau de l’événement ou dans l’objet metadata au niveau du produit, à l’intérieur de products[]. Elles restent disponibles pour Liquid, Currents et la segmentation, tout comme les champs de niveau supérieur.

Validation et résolution des problèmes des événements

Lorsque vous envoyez un événement eCommerce recommandé via /users/track ou l’un des SDK de Braze, Braze valide le payload par rapport au schéma JSON de l’événement pendant le traitement de l’événement recommandé. La validation s’exécute automatiquement sur chaque événement dont le nom correspond exactement à un événement recommandé (par exemple, ecommerce.order_placed ou ecommerce.cart_updated).

Ce que nous validons

Pour chaque événement dont le nom correspond à un événement eCommerce recommandé, Braze vérifie les éléments suivants :

Vérification	Exemple
Nom de l’événement	Doit être exact. Par exemple, `ecommerce.cart_updated` est correct, mais pas `ecommerce.Cart_Updated`, `cartupdated` ni `cart_updated`.
Présence des propriétés obligatoires	`order_placed` requiert `order_id`, `total_value`, `currency`, `products` et `source`.
Types de données corrects	`total_value` doit être un nombre ; `currency` doit être une chaîne de caractères ; `products` doit être un tableau.
Aucune propriété supplémentaire au niveau supérieur	Les champs personnalisés placés sous les propriétés provoquent un échec. Utilisez plutôt l’objet `metadata`.
Contraintes de valeur	Les champs monétaires doivent être ≥ `0`. `currency` doit être une chaîne de caractères ISO 4217 valide.
Champs par produit	Chaque élément de `products[]` doit inclure `product_id`, `product_name`, `variant_id`, `quantity` et `price`.

Pourquoi nous validons

Les événements eCommerce alimentent des fonctionnalités qui dépendent de données cohérentes et prévisibles, notamment le suivi du chiffre d’affaires, l’étiquette Liquid {% shopping_cart %}, le déclencheur de panier abandonné et le reporting. Lorsque les payloads s’écartent du schéma, ces fonctionnalités produisent des inexactitudes silencieuses (totaux de chiffre d’affaires erronés, paniers manquants, déclencheurs défaillants). La validation impose le contrat dès le départ, afin que les fonctionnalités en aval se comportent de manière prévisible.

Lorsque la validation réussit

L’événement est traité comme un événement eCommerce recommandé, avec l’ensemble du post-traitement associé. Consultez les événements eCommerce recommandés pour la liste complète des comportements déclenchés par chaque type d’événement.

Vérifier qu’un événement a réussi

Après l’envoi d’un événement, vous pouvez confirmer qu’il a été accepté et correctement traité à l’aide de l’une des méthodes suivantes :

Journal des événements utilisateurs : Ouvrez le profil de l’utilisateur dans le tableau de bord et examinez son activité. Les événements recommandés apparaissent avec leur payload complet de propriétés : vous pouvez ainsi confirmer que l’événement est bien arrivé et que les valeurs correspondent à ce que vous avez envoyé.
Rapport sur les événements personnalisés : Accédez à Analyse > Rapport sur les événements personnalisés pour consulter le nombre agrégé de chaque événement recommandé au fil du temps. C’est utile pour confirmer que le trafic de production circule comme prévu une fois votre intégration en ligne.
Utilisateurs test : Marquez un utilisateur de votre espace de travail de développement comme utilisateur test, puis déclenchez des événements depuis votre intégration pour cet utilisateur. Les utilisateurs test sont signalés dans le tableau de bord, ce qui facilite l’isolement et l’inspection du comportement de bout en bout.

Lorsque la validation échoue

L’événement n’est pas traité comme un événement recommandé. Plus précisément :

L’événement est entièrement abandonné. Les événements eCommerce recommandés non valides n’arrivent pas sur le profil utilisateur, n’apparaissent pas dans Currents et ne sont pas disponibles pour la segmentation.
Les fonctionnalités en aval liées aux événements recommandés ne s’exécutent pas, notamment :
- Le suivi du chiffre d’affaires (reporting du chiffre d’affaires, champs calculés de l’utilisateur tels que total_revenue)
- Les mises à jour de l’objet panier sur le profil utilisateur
- Les déclencheurs Mettre à jour le panier ou Passer une commande dans les Canvas et les Campaigns

La manière dont les erreurs sont signalées dépend du chemin d’ingestion :

REST API (/users/track) : Chaque événement non valide est signalé dans le tableau d’erreurs de la réponse. Chaque entrée vous indique quel événement a échoué (index) et pourquoi (type). Le champ message de niveau supérieur indique toujours « success », ce qui signifie simplement que votre requête a atteint Braze, et non que chaque événement était valide. Vérifiez toujours la présence d’un tableau d’erreurs dans la réponse.
SDK de Braze : Les appels SDK renvoient une réponse immédiatement et la validation s’exécute en arrière-plan : les erreurs ne sont donc pas renvoyées à votre application. Pour être informé des échecs de validation des événements eCommerce, surveillez l’e-mail récapitulatif des échecs (voir Identifier les échecs).

Exemple de réponse d’erreur de l’API

L’endpoint /users/track renvoie des erreurs au niveau des champs, indiquant quelles propriétés ont échoué et pourquoi. Notez que le message de niveau supérieur peut renvoyer "success", car l’événement a été accepté dans le pipeline ; le tableau errors vous indique quels champs ont échoué à la validation du schéma. Consultez l’exemple de réponse d’erreur suivant.

{
 "message": "success",
 "errors": [{ "index": 0, "input_array": "purchases", "type": "'currency' must be an ISO 4217 currency" }]
}

Les échecs sont également classés en interne et agrégés pour l’e-mail récapitulatif des échecs :

Type d’échec	Signification	Exemple
`missing_property`	Un champ obligatoire est absent.	`order_placed` envoyé sans `order_id`.
`extra_property`	Un champ non défini par le schéma a été ajouté.	Un champ personnalisé `gift_wrapped` placé au niveau supérieur de `properties` au lieu de `metadata`.
`unexpected_data_type`	Un champ n’est pas du bon type.	`total_value: "29.99"` (chaîne de caractères) au lieu de `29.99` (nombre).

Remarque

Les noms d’événements qui ne correspondent pas exactement à un événement recommandé (par exemple, ecommerce.OrderPlaced) ignorent entièrement la validation et sont enregistrés comme des événements personnalisés ordinaires. Ils apparaissent dans Currents et dans la segmentation sous le nom que vous avez envoyé, mais ne bénéficient d’aucun traitement réservé aux événements recommandés et ne génèrent aucune entrée errors dans la réponse.

Identifier les échecs

Braze envoie par e-mail aux administrateurs de votre espace de travail un récapitulatif des échecs de validation des événements recommandés, afin que vous puissiez identifier et corriger les problèmes d’intégration sans surveiller manuellement chaque événement.

L’e-mail récapitulatif comprend :

Nombre total d’erreurs : Le nombre d’erreurs pour la période de reporting.
Erreurs par événement : Une répartition du nombre d’événements ayant échoué pour chaque type d’événement recommandé (par exemple, ecommerce.cart_updated et ecommerce.order_placed). Utilisez-la pour identifier les événements de votre intégration à traiter en priorité.
Erreurs par source : Une répartition entre API et SDK, pour déterminer précisément quelle intégration génère les échecs.

Si vous ne recevez pas ces e-mails ou souhaitez vérifier la liste des destinataires, contactez votre équipe de compte Braze.

Diagnostiquer et corriger les échecs

Lorsque vous recevez un e-mail récapitulatif des échecs :

Identifiez l’événement et la source en échec. L’e-mail répartit les échecs par nom d’événement et par source d’intégration (sdk ou rest_api), afin que vous sachiez précisément quelle intégration doit être corrigée. Si plusieurs sources envoient le même événement (par exemple, le SDK de votre boutique en ligne et un webhook backend qui envoient tous deux cart_updated), traitez-les séparément.
Comparez votre payload au schéma dans Schémas d’événements. La plupart des échecs relèvent de l’un de ces trois cas :
- missing_property : Un champ obligatoire est absent. Pour résoudre ce problème, ajoutez le champ obligatoire.
- extra_property : Un champ personnalisé se trouve au niveau supérieur de properties. Pour résoudre ce problème, déplacez le champ personnalisé dans metadata (au niveau de l’événement) ou dans products[].metadata (par produit).
- unexpected_data_type : Une valeur n’est pas du bon type (par exemple, total_value envoyé sous forme de chaîne de caractères). Pour résoudre ce problème, convertissez la valeur avant l’envoi.
Testez le payload corrigé dans un espace de travail de développement avant de le déployer en production. Envoyez un événement test connu pour un utilisateur test, puis vérifiez le comportement attendu de l’événement recommandé sur le profil de cet utilisateur (par exemple, la mise à jour de l’objet panier, l’incrémentation du chiffre d’affaires ou le déclenchement du panier abandonné).
Surveillez le prochain e-mail d’échec pour confirmer que le nombre d’échecs pour cet événement, cette source et ce type tombe à zéro.

Pour connaître toutes les exigences de propriétés par événement, consultez Schémas d’événements.

New Stuff!

Événements recommandés

Événements eCommerce recommandés

Fonctionnement des événements eCommerce

Nommage des événements

Schémas d’événements

Déploiement côté client

Propriétés de l’événement

Exemple REST API

Déploiement côté client

Propriétés de l’événement

Propriétés du produit (products[])

Déploiement côté client

Propriétés de l’événement

Propriétés du produit (products[])

Exemple REST API

Déploiement côté client

Propriétés de l’événement

Propriétés du produit (products[])

Exemple REST API

Déploiement côté client

Propriétés de l’événement

Propriétés du produit (products[])

Exemple REST API

Déploiement côté client

Propriétés de l’événement

Propriétés du produit (products[])

Exemples REST API

Post-traitement des événements eCommerce

Détails de mise en œuvre

Points de données et facturation

Limite de taille des événements

Gestion des devises

Champ source

Flexibilité des métadonnées

Validation et résolution des problèmes des événements

Ce que nous validons

Pourquoi nous validons

Lorsque la validation réussit

Vérifier qu’un événement a réussi

Lorsque la validation échoue

Exemple de réponse d’erreur de l’API

Identifier les échecs

Diagnostiquer et corriger les échecs

Propriétés du produit (`products[]`)

Propriétés du produit (`products[]`)

Propriétés du produit (`products[]`)

Propriétés du produit (`products[]`)

Propriétés du produit (`products[]`)