É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 recommandés pour le commerce électronique
Les événements recommandés pour le commerce électronique 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, 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 parcours 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 à l’aide du filtrage sur les propriétés de produit imbriquées via les extensions de segments, personnaliser les messages de panier abandonné avec l’étiquette Liquid {% shopping_cart %} et alimenter des fonctionnalités BrazeAITM 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 propre à chaque fonctionnalité de votre côté.

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 dotés de noms et de schémas de propriétés prédéfinis. Vous les envoyez à l’aide du SDK de Braze, de l’endpoint REST API /users/track, de l’ingestion de données cloud (CDI) ou de l’importation CSV, 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 au type d’événement, comme le calcul des champs de chiffre d’affaires et la gestion de l’état du panier dans les profils utilisateurs.
Les événements eCommerce fonctionnent partout où les autres événements personnalisés fonctionnent : déclencheurs et filtres basés sur les événements personnalisés effectués, reporting des événements personnalisés, etc. Cependant, leur validation de schéma débloque des fonctionnalités supplémentaires, notamment :
- Les actions de déclenchement « Places order » dans les Campaigns, les Canvas, les étapes Parcours d’action, les déclencheurs de messages in-app et la suppression des Content Cards
- Les champs eCommerce calculés du profil utilisateur (Chiffre d’affaires total, Total des commandes, Total des remboursements)
- La gestion de l’état du panier pour les parcours de panier abandonné
- Des données plus riches pour les fonctionnalités BrazeAITM comme les événements prédictifs, la prédiction du taux d’attrition et les recommandations d’articles
Vous pouvez également référencer les é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 Campaign par événement avec des événements ecommerce.product_viewed, créer un Segment qui filtre sur les événements ecommerce.checkout_started ou exporter des événements ecommerce.order_placed via Currents.
Dénomination 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 le nom d’un é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 pas 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.


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 souvent de l’achèvement d’une logique côté serveur, comme votre processus de remboursement. Pour des exemples de mise en œuvre 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 de détail 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.
Mise en œuvre côté client
Utilisez les API d’événements eCommerce du SDK lorsqu’elles sont disponibles. Pour des exemples de mise en œuvre 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 d’où 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éclenchement des catalogues Braze pour les alertes de retour en stock et de baisse de prix. Valeurs acceptées : "price_drop", "back_in_stock". |
catalog_name |
Chaîne de caractères | Non | Le catalogue auquel appartient un abonnement de retour en stock ou de baisse de prix créé à partir de cet événement. S’il est omis, le catalogue de secours de l’espace de travail est utilisé. Doit être une propriété de premier niveau ; un catalog_name imbriqué dans metadata est ignoré. |
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"],
"catalog_name": "running_shoes",
"metadata": {
"category": "Running Shoes",
"brand": "Shoe Brand"
}
}
}
]
}
Déclenchez cet événement chaque fois que le contenu du panier d’un utilisateur change.
Mise en œuvre côté client
Utilisez les API d’événements eCommerce du SDK lorsqu’elles sont disponibles. Pour des exemples de mise en œuvre propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.
Vous pouvez envoyer cet événement de deux manières :
- Remplacement complet du panier : Omettez
actionou définissezactionsurreplace. Incluez l’ensemble des lignes d’articles dansproductsavec des quantités absolues (nombre total d’unités par variante dans le panier). Vous devez incluretotal_value. - Mises à jour incrémentielles du panier : Définissez
actionsuraddouremove. Incluez uniquement les lignes d’articles modifiées. Chaquequantitycorrespond 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. Pourremove, Braze diminue la quantité de la ligne et supprime la ligne lorsque la quantité atteint0. - Pour
addetremove,total_valueest facultatif et n’est pas stocké dans le panier ; pour un panier mis à jour uniquement avecaddouremove, l’étiquette{% shopping_cart %}renvoie à la place la somme dupricede chaque produit multiplié par saquantity.
- Pour

Utilisez soit des mises à jour incrémentielles du panier (add ou remove), soit le remplacement complet (aucune action ou replace) pour un panier donné. Mélanger les deux approches pour le même cart_id est déconseillé et peut entraîner un état de panier incohérent dans Braze.
Pour déclencher l’envoi de messages à partir de cet événement, utilisez le déclencheur Perform Cart Updated Event dans les Canvas et les Campaigns. Ce déclencheur inclut un traitement spécial pour empêcher le panier de progresser dans l’entonnoir d’achat.
Le panier crée un objet de mappage des paniers dans le profil utilisateur, qui alimente l’étiquette Liquid {% shopping_cart %}. Le panier expire après 30 jours sans mise à jour et est supprimé lors du traitement du prochain événement eCommerce de l’utilisateur. Si deux profils utilisateurs fusionnent, Braze conserve les deux paniers.
ID du panier après le paiement ou la commande
Une fois que Braze a reçu ecommerce.checkout_started ou ecommerce.order_placed pour un cart_id, ce panier n’est plus considéré comme abandonné :
- Les futurs événements
ecommerce.cart_updatedavec le mêmecart_idne déclenchent pas Perform Cart Updated Event - L’étiquette
{% shopping_cart %}est interrompue par défaut - Après
ecommerce.order_placed, les produits du panier sont effacés et les mises à jour ultérieures du panier pour cecart_idsont ignorées jusqu’à l’expiration du panier
Générez un nouveau cart_id lorsque l’acheteur commence un nouveau panier.
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. Ne réutilisez pas un cart_id après ecommerce.checkout_started ou ecommerce.order_placed ; consultez ID du panier après le paiement ou la commande. |
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, et stocké comme total du panier. Facultatif lorsque action vaut add ou remove.Lorsque action vaut add ou remove, la valeur n’est pas stockée dans le panier et n’efface pas un total stocké précédemment. Lorsqu’un panier est mis à jour uniquement avec add ou remove, aucune total_value n’est stockée et l’étiquette {% shopping_cart %} additionne le price de chaque produit multiplié par sa quantity. |
subtotal_value |
Float | Non | Sous-total du panier (après remise, avant taxes et frais de livraison). Non stocké dans le panier et non disponible via l’étiquette Liquid {% shopping_cart %}. |
tax |
Float | Non | Total des taxes appliquées au panier. Non stocké dans le panier et non disponible via l’étiquette Liquid {% shopping_cart %}. |
shipping |
Float | Non | Coût total de livraison du panier. Non stocké dans le panier et non disponible via l’étiquette Liquid {% shopping_cart %}. |
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 (aucune action ou 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 d’où 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 (aucune action ou 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 « Checkout » ou en arrivant sur la page de paiement).
Mise en œuvre côté client
Utilisez les API d’événements eCommerce du SDK lorsqu’elles sont disponibles. Pour des exemples de mise en œuvre propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.
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 d’où 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é.
Mise en œuvre côté client
Utilisez les API d’événements eCommerce du SDK lorsqu’elles sont disponibles. Pour des exemples de mise en œuvre propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Cet événement est la principale source de chiffre d’affaires. Il incrémente total_revenue de la valeur indiquée dans total_value et incrémente total_orders de 1 dans 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 d’où 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.
Mise en œuvre côté client
Utilisez logCustomEvent. Pour des exemples de mise en œuvre propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Cet événement décrémente total_orders de 1 dans le profil utilisateur. Il n’affecte pas 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 d’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 d’où 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 émis.
Mise en œuvre côté client
Utilisez logCustomEvent. Pour des exemples de mise en œuvre propres à chaque plateforme, consultez Enregistrer des événements eCommerce via le SDK de Braze.

Cet événement décrémente total_revenue de la valeur indiquée dans total_value et incrémente total_refunds dans le profil utilisateur. Pour les remboursements partiels, définissez total_value sur le seul montant remboursé, et non sur le total de la commande d’origine.
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 d’origine. |
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 d’où 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). |
Exemples REST API
{
"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 fait 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 | Ce que Braze fait automatiquement |
|---|---|
ecommerce.order_placed |
Incrémente Chiffre d’affaires total de total_value et Total des commandes de 1 dans le profil utilisateur. |
ecommerce.order_cancelled |
Décrémente Total des commandes de 1. |
ecommerce.order_refunded |
Décrémente Chiffre d’affaires total de total_value et incrémente Valeur totale des remboursements. |
ecommerce.cart_updated |
Crée ou met à jour l’objet de mappage des paniers dans le profil utilisateur (payloads de panier complet ou mises à jour incrémentielles du panier avec une action facultative : 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 BrazeAITM (comme les recommandations d’articles). |
ecommerce.checkout_started |
Aucune modification du profil utilisateur. Disponible pour la segmentation et le déclenchement (par exemple, les parcours de paiement abandonné). |

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à votre reporting en USD, codez la devise en dur sur USD 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 consommation de 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 déclenchés de campagne et de Canvas, les trigger_properties envoyées à /campaigns/trigger/send et /canvas/trigger/send sont soumises à une limite par défaut plus stricte de 51 200 octets (50 Ko).
En règle générale, n’envoyez que 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, stocks 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 sélective pour le contexte propre à la commande ou au produit dont vos messages auront besoin.
Gestion des devises
Braze convertit automatiquement les montants dans une devise autre que l’USD en USD, en utilisant 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.

Si vous opérez 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 comme au niveau du produit acceptent des paires clé-valeur arbitraires : vous pouvez ainsi ajouter des dimensions personnalisées sans modifier le schéma principal. Parmi les exemples courants, citons order_status_url, gift_wrapped, loyalty_points_earned ou warehouse_id. Ces propriétés sont disponibles dans la personnalisation Liquid, les exportations Currents et la segmentation via les extensions de segments.

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 pour 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, contrairement à ecommerce.Cart_Updated, cartupdated ou 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 une chaîne de caractères et products un tableau. |
| Aucune propriété supplémentaire au premier niveau | Les champs personnalisés placés sous les propriétés entraînent 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 ce contrat en amont 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 obtenir la liste complète des comportements déclenchés par chaque type d’événement.
Vérifier qu’un événement a abouti
Après avoir envoyé un événement, vous pouvez confirmer qu’il a été accepté et traité correctement de l’une des manières 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, ce qui vous permet de confirmer que l’événement a bien été reçu 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 voir le nombre total 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 : Désignez 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 dans 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 comme
total_revenue) - Les mises à jour de l’objet panier dans le profil utilisateur
- Les déclencheurs Update Cart ou Place Order dans Canvas et les Campaigns
- Le suivi du chiffre d’affaires (reporting du chiffre d’affaires, champs calculés de l’utilisateur comme
La façon 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 indique quel événement a échoué (index) et pourquoi (type). Le champ message de premier niveau 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 immédiatement une réponse et la validation s’exécute en arrière-plan, de sorte que les erreurs ne sont 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 Trouver les échecs).
Exemple de réponse d’erreur de l’API
L’endpoint /users/track renvoie des erreurs au niveau des champs, qui indiquent quelles propriétés ont échoué et pourquoi. Notez que le message de premier niveau 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 au premier niveau de properties au lieu de se trouver dans 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). |

Les noms d’événements qui ne correspondent pas exactement à un événement recommandé (par exemple, ecommerce.OrderPlaced) échappent 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 propre aux événements recommandés et ne génèrent aucune entrée errors dans la réponse.
Trouver 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 sur la période couverte.
- Erreurs par événement : La répartition du nombre d’événements en échec pour chaque type d’événement recommandé (par exemple,
ecommerce.cart_updatedetecommerce.order_placed). Utilisez-la pour identifier les événements de votre intégration à traiter en priorité. - Erreurs par source : La répartition entre API et SDK, pour cibler précisément l’intégration à l’origine des échecs.
Si vous ne recevez pas ces e-mails ou si vous 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 sépare les échecs par nom d’événement et par source d’intégration (
sdkourest_api), ce qui vous permet de cibler l’intégration à corriger. 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 deuxcart_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 premier niveau deproperties. Pour résoudre ce problème, déplacez le champ personnalisé dansmetadata(au niveau de l’événement) ou dansproducts[].metadata(par produit).unexpected_data_type: Une valeur n’est pas du bon type (par exemple,total_valueenvoyé 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é dans le profil de cet utilisateur (par exemple, la mise à jour de l’objet panier, l’augmentation du chiffre d’affaires ou l’activation du déclencheur de panier abandonné).
- Surveillez le prochain e-mail d’échecs pour confirmer que le nombre d’échecs pour cet événement, cette source et ce type est tombé à zéro.
Pour connaître toutes les exigences de propriétés par événement, consultez Schémas d’événements.