Skip to content

Empfohlene Events

Empfohlene Events basieren auf einem Framework, das standardisierte angepasste Events mit definierten JSON-Schemata sendet. Wenn Sie ein empfohlenes Event senden, validiert Braze es bei der Aufnahme gegen sein Schema und wendet eine spezialisierte Nachbearbeitung an – wie automatische Feldberechnungen oder Warenkorb-Verwaltung –, die generische angepasste Events nicht erhalten. Für bestimmte branchenspezifische Event-Sets unterstützt Braze außerdem eine spezielle Behandlung, wie z. B. dedizierte aktionsbasierte Trigger für Campaigns und Canvases.

Empfohlene E-Commerce-Events decken sechs Schritte der Kauf-Journey ab: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled und order_refunded. Wenn Sie diese Events erfolgreich senden, validiert Braze die Daten und stellt sie einer wachsenden Reihe von Plattform-Features zur Verfügung.

Zu diesen Features gehören Canvas-Templates für abgebrochenes Browsen, Warenkorb-Abbruch, abgebrochenen Checkout und Bestellbestätigungs-Flows; E-Commerce-Reporting; sowie berechnete Nutzerprofil-Felder für Gesamtumsatz, Gesamtbestellungen und Gesamterstattungen. Sie können außerdem Segmente mithilfe verschachtelter Produkteigenschafts-Filterung über Segmenterweiterungen erstellen, Warenkorb-Abbruch-Nachrichten mit dem {% shopping_cart %} Liquid-Tag personalisieren und BrazeAITM-Funktionen wie Predictive Events, Predictive Churn und Artikelempfehlungen sowie weitere Funktionen nutzen.

Da diese Events einem definierten Schema folgen, kann jedes unterstützte Feature die strukturierten Daten ohne benutzerdefiniertes Property-Mapping oder Feature-spezifische Konfiguration auf Ihrer Seite lesen.

So funktionieren E-Commerce-Events

E-Commerce-Events sind angepasste Events mit vordefinierten Namen und Eigenschafts-Schemata. Sie senden sie über das Braze SDK oder den /users/track REST-API-Endpunkt, und Braze validiert jedes Event bei der Aufnahme gegen sein Schema. Wenn die Validierung erfolgreich ist, wendet Braze automatisch eine für diesen Event-Typ spezifische Nachbearbeitung an, wie z. B. die Berechnung von Umsatzfeldern und die Verwaltung des Warenkorb-Status in Nutzerprofilen.

E-Commerce-Events funktionieren überall dort, wo auch andere angepasste Events funktionieren: Trigger und Filter für durchgeführte angepasste Events, Reporting zu angepassten Events und mehr. Ihre Schema-Validierung schaltet jedoch zusätzliche Funktionen frei, darunter:

  • „Bestellung aufgegeben“-Trigger-Aktionen in Campaigns, Canvases, Aktionspfaden, In-App-Nachricht-Triggern und Content-Card-Entfernung
  • Berechnete E-Commerce-Nutzerprofil-Felder (Gesamtumsatz, Gesamtbestellungen, Gesamterstattungen)
  • Warenkorb-Status-Verwaltung für Warenkorb-Abbruch-Flows
  • Reichhaltigere Daten für BrazeAITM-Features wie Predictive Events, Predictive Churn und Artikelempfehlungen

Sie können E-Commerce-Events auch namentlich überall dort referenzieren, wo die Plattform angepasste Events unterstützt. Beispielsweise können Sie eine aktionsbasierte Campaign mit ecommerce.product_viewed-Events triggern, ein Segment erstellen, das nach ecommerce.checkout_started-Events filtert, oder ecommerce.order_placed-Events über Currents exportieren.

Event-Benennung

Event-Namen sind exakt, Groß-/Kleinschreibung-sensitiv und durch Punkte getrennt. Verwenden Sie immer das kanonische Format. Wenn ein Event-Name nicht exakt einem der sechs kanonischen Namen entspricht, behandelt Braze ihn als Standard-angepasstes-Event und es findet keine E-Commerce-Nachbearbeitung statt.

Sie können Events nicht anpassen oder umbenennen.

  • Korrekt: ecommerce.order_placed
  • Falsch: order.placed, eCommerce_order_placed, Order_Placed

Event-Schemata

Die sechs empfohlenen E-Commerce-Events bilden Phasen der Kauf-Journey ab. Lösen Sie jedes Event in dem Moment aus, in dem die Nutzer:in die entsprechende Aktion abschließt.

Diagramm der Nutzer-Journey durch alle sechs empfohlenen E-Commerce-Events: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled und order_refunded.

Lösen Sie dieses Event aus, wenn eine Nutzer:in eine Produktdetailseite aufruft. Dieses Event ist kompatibel mit den Braze-Katalog-Funktionen Wieder-auf-Lager-Benachrichtigungen und Preissenkungsbenachrichtigungen.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaftsname Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner (z. B. SKU oder Artikel-ID).
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Produktvarianten-Bezeichner (z. B. shirt_medium_blue).
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite für weitere Details.
price Gleitkommazahl Ja Varianten-Stückpreis zum Zeitpunkt der Ansicht.
currency String Ja Dreistelliger ISO-4217-Code (z. B. USD oder EUR).
source String Ja Quelle, von der das Event stammt (z. B. web, ios oder android).
type String-Array Nein Erforderlich, um die Braze-Katalog-Trigger-Features für Wieder-auf-Lager- und Preissenkungsbenachrichtigungen zu nutzen. Akzeptierte Werte: "price_drop", "back_in_stock"
metadata Objekt Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: sku (String)

REST-API-Beispiel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "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": {
          "sku": "UB-BLK-11-SKU",
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Lösen Sie dieses Event jedes Mal aus, wenn sich der Inhalt des Warenkorbs einer Nutzer:in ändert.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Sie können dieses Event auf zwei Arten senden:

  • Vollständiger Warenkorb-Ersatz: Lassen Sie action weg oder setzen Sie action auf replace. Fügen Sie den vollständigen Satz an Positionen in products mit absoluten Mengen (Gesamteinheiten pro Variante im Warenkorb) ein. Sie müssen total_value angeben.
  • Inkrementelle Warenkorb-Updates: Setzen Sie action auf add oder remove. Fügen Sie nur die geänderten Positionen ein. Jede quantity ist die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten, nicht die Gesamtmenge im Warenkorb. Bei add erhöht Braze die Positionsmenge oder fügt eine neue Position hinzu. Bei remove verringert Braze die Positionsmenge und entfernt die Position, wenn die Menge 0 erreicht. total_value ist bei add und remove optional.

Um Messaging über dieses Event zu triggern, verwenden Sie den Trigger Warenkorb-Aktualisierungs-Event durchführen in Canvas und Campaigns. Dieser Trigger enthält eine spezielle Behandlung, um zu verhindern, dass der Warenkorb im Shopping-Funnel weiter voranschreitet.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
cart_id String Ja Eindeutiger Bezeichner für den Warenkorb. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in geteilt.
action String Nein add (Menge erhöhen oder neue Position hinzufügen), remove (Menge verringern; Position wird bei 0 entfernt) oder replace (vollständiger Warenkorb-Ersatz, identisch mit dem Weglassen von action).
total_value Gleitkommazahl Bedingt Erforderlich, wenn action weggelassen wird oder replace ist. Optional bei action add oder remove.
subtotal_value Gleitkommazahl Nein Zwischensumme des Warenkorbs (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamte auf den Warenkorb angewandte Steuer.
shipping Gleitkommazahl Nein Gesamte Versandkosten für den Warenkorb.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Positionen für dieses Update. Beim vollständigen Ersatz (kein action oder replace) den vollständigen Warenkorb mit absoluten Mengen einfügen. Bei add oder remove nur geänderte Positionen einfügen; siehe Produkteigenschaften.
source String Ja Quelle, von der das Event stammt.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare für zusätzliche Daten auf Event-Ebene.

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Beim vollständigen Ersatz (kein action oder replace) die Einheiten im Warenkorb für diese Position. Bei add oder remove die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

Lösen Sie dieses Event aus, wenn die Nutzer:in den Checkout-Prozess startet (z. B. „Zur Kasse“ auswählt oder auf der Checkout-Seite landet).

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Typ Erforderlich Beschreibung
checkout_id String Ja Eindeutiger Bezeichner für die Checkout-Sitzung.
cart_id String Nein Warenkorb-Bezeichner. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in geteilt.
total_value Gleitkommazahl Ja Gesamter Geldwert des Checkouts.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamte auf den Checkout angewandte Steuer.
shipping Gleitkommazahl Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Artikel im Checkout. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: checkout_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare (z. B. Farbe, Größe).

REST-API-Beispiel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

{
  "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"
        }
      }
    }
  ]
}

Lösen Sie dieses Event aus, wenn eine Bestellung erfolgreich abgeschlossen oder die Zahlung bestätigt wurde.

Clientseitige Implementierung

Verwenden Sie die SDK-E-Commerce-Event-APIs, sofern verfügbar. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die Bestellung.
cart_id String Nein Warenkorb-Bezeichner. Wird über Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in geteilt.
total_value Gleitkommazahl Ja Gesamter Geldwert der Bestellung.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamte auf die Bestellung angewandte Steuer.
shipping Gleitkommazahl Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der auf die Bestellung angewandten Rabatte.
discounts Array Nein Detaillierte Liste der angewandten Rabatte.
products Array Ja Artikel in der Bestellung. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST-API-Beispiel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

{
  "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"
        }
      }
    }
  ]
}

Lösen Sie dieses Event aus, wenn eine Bestellung storniert wird.

Clientseitige Implementierung

Verwenden Sie logCustomEvent. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Typ Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die Bestellung.
total_value Gleitkommazahl Ja Gesamter Geldwert der stornierten Bestellung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Verringerung.
subtotal_value Gleitkommazahl Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Gleitkommazahl Nein Gesamte auf die Bestellung angewandte Steuer.
shipping Gleitkommazahl Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der auf die Bestellung angewandten Rabatte.
discounts Array Nein Detaillierte Liste der angewandten Rabatte.
cancel_reason String Ja Grund für die Stornierung der Bestellung.
products Array Ja Artikel in der stornierten Bestellung. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String)

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST-API-Beispiel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "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"
        }
      }
    }
  ]
}

Lösen Sie dieses Event aus, wenn eine vollständige oder teilweise Erstattung erfolgt.

Clientseitige Implementierung

Verwenden Sie logCustomEvent. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
order_id String Ja Eindeutiger Bezeichner für die ursprüngliche Bestellung.
total_value Gleitkommazahl Ja Gesamter Geldwert der Erstattung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Erhöhung von total_refunds.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Gleitkommazahl Nein Gesamtbetrag der ursprünglich angewandten Rabatte.
discounts Array Nein Detaillierte Liste der Rabatte.
products Array Ja Erstattete Artikel. Siehe Produkteigenschaften-Untertabelle.
source String Ja Quelle, von der das Event stammt.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare. Erkannte Untereigenschaft: order_status_url (String).

Produkteigenschaften (products[])

Eigenschaft Datentyp Erforderlich Beschreibung
product_id String Ja Eindeutiger Produktbezeichner.
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Varianten-Bezeichner.
image_url String Nein Produktbild-URL.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Gleitkommazahl Ja Varianten-Stückpreis.
metadata Objekt Nein Flexible Schlüssel-Wert-Paare (z. B. color oder size).

REST-API-Beispiele

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "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"
        }
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "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"
        }
      }
    }
  ]
}

E-Commerce-Event-Nachbearbeitung

Wenn Sie ein E-Commerce-Event senden, validiert Braze es gegen das erwartete Schema für diesen Event-Namen.

Die folgende Tabelle fasst zusammen, was Braze automatisch für jedes Event tut, wenn die Validierung erfolgreich ist. Informationen dazu, was bei fehlgeschlagener Validierung passiert, finden Sie unter Event-Validierung und Fehlerbehebung.

Event Was Braze automatisch tut
ecommerce.order_placed Erhöht Gesamtumsatz um total_value und Gesamtbestellungen um 1 im Nutzerprofil.
ecommerce.order_cancelled Verringert Gesamtbestellungen um 1.
ecommerce.order_refunded Verringert Gesamtumsatz um total_value und erhöht Gesamterstattungswert.
ecommerce.cart_updated Erstellt oder aktualisiert das Warenkorb-Mapping-Objekt im Nutzerprofil (vollständige Warenkorb-Payloads oder inkrementelle Warenkorb-Updates mit optionalem action: add, remove oder replace). Der Warenkorb läuft nach 30 Tagen ohne Update ab.
ecommerce.product_viewed Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung, Triggering und BrazeAITM-Features (wie Artikelempfehlungen).
ecommerce.checkout_started Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung und Triggering (z. B. abgebrochene Checkout-Flows).

E-Commerce-Events implementieren

Sie können E-Commerce-Events über den /users/track-Endpunkt (serverseitig) oder über die Braze SDKs (clientseitig) senden. SDK-Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Events serverseitig senden

Verwenden Sie den /users/track-Endpunkt, um E-Commerce-Events von Ihrem Backend zu senden. Jedes Event erfordert den exakten Event-Namen, die external_id der Nutzer:in und ein Eigenschafts-Objekt, das dem Event-Schema entspricht.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

POST /users/track

{
  "events": [
    {
      "external_id": "user_abc123",
      "name": "ecommerce.order_placed",
      "time": "2026-04-26T14:32:00Z",
      "properties": {
        "order_id": "order_7891011",
        "total_value": 84.99,
        "currency": "USD",
        "source": "custom_api",
        "total_discounts": 10.00,
        "products": [
          {
            "product_id": "sku_2001",
            "product_name": "Trail Runner Pro",
            "variant_id": "var_2001_black_10",
            "quantity": 1,
            "price": 94.99,
            "metadata": {
              "color": "black",
              "size": "10"
            }
          }
        ],
        "metadata": {
          "gift_wrapped": true,
          "loyalty_points_earned": 170
        }
      }
    }
  ]
}

Datenpunkte und Abrechnung

E-Commerce-Events verbrauchen keine Datenpunkte. Sie können sie ohne Auswirkungen auf Ihre Datenpunkt-Nutzung protokollieren.

Event-Größenlimit

Event-Eigenschaften, die an /users/track gesendet werden, sind auf 102.400 Bytes (100 KB) pro Event begrenzt. Für getriggerte Campaign- und Canvas-Nachrichten haben die trigger_properties, die an /campaigns/trigger/send und /canvas/trigger/send gesendet werden, ein strengeres Standardlimit von 51.200 Bytes (50 KB).

Als Best Practice senden Sie nur die Produktinformationen, die Sie zum Triggern, Personalisieren oder Zuordnen des Events benötigen. Speichern Sie umfangreichere Produktdetails – wie Beschreibungen, vollständige Variantenlisten, Lagerbestand oder alternative Bilder – in Braze-Katalogen. Referenzieren Sie diese Details beim Senden von Nachrichten über product_id oder variant_id. Verwenden Sie das metadata-Objekt selektiv für bestell- oder produktspezifischen Kontext, den das Messaging nutzen wird.

Währungsbehandlung

Braze rechnet Nicht-USD-Währungswerte automatisch anhand des Wechselkurses am Tag der Event-Meldung in USD um. Dieser umgerechnete Wert wird in den Umsatzmetriken angezeigt.

Quellfeld

Die Eigenschaft „source“ ist ein erforderlicher String, der angibt, woher das Event stammt. Zum Beispiel shopify, in-store POS oder custom_api. Dies hilft Ihnen, Integrationsquellen bei der Analyse von Daten in Currents-Exporten oder bei der Fehlerbehebung von Validierungsproblemen zu unterscheiden.

Metadata-Flexibilität

Sowohl die Metadata-Objekte auf Event-Ebene als auch auf Produktebene akzeptieren beliebige Schlüssel-Wert-Paare, sodass Sie benutzerdefinierte Dimensionen anhängen können, ohne das Kernschema zu ändern. Gängige Beispiele sind order_status_url, gift_wrapped, loyalty_points_earned oder warehouse_id. Diese Eigenschaften sind in der Liquid-Personalisierung, in Currents-Exporten und in der Segmentierung über Segmenterweiterungen verfügbar.

Event-Validierung und Fehlerbehebung

Wenn Sie ein empfohlenes E-Commerce-Event über /users/track oder ein Braze SDK senden, validiert Braze die Payload gegen das JSON-Schema des Events während der Verarbeitung des empfohlenen Events. Die Validierung wird automatisch bei jedem Event ausgeführt, dessen Name exakt einem empfohlenen Event entspricht (z. B. ecommerce.order_placed oder ecommerce.cart_updated).

Was wir validieren

Für jedes Event, dessen Name einem empfohlenen E-Commerce-Event entspricht, prüft Braze:

Prüfung Beispiel
Event-Name Muss exakt sein. Zum Beispiel ist ecommerce.cart_updated korrekt – nicht ecommerce.Cart_Updated, cartupdated oder cart_updated.
Erforderliche Eigenschaften vorhanden order_placed erfordert order_id, total_value, currency, products und source.
Korrekte Datentypen total_value muss eine Zahl sein; currency muss ein String sein; products muss ein Array sein.
Keine zusätzlichen Eigenschaften auf oberster Ebene Benutzerdefinierte Felder unter „properties“ führen zum Fehlschlagen. Verwenden Sie stattdessen das metadata-Objekt.
Wertbeschränkungen Geldbetragsfelder müssen ≥ 0 sein. currency muss ein gültiger ISO-4217-String sein.
Felder pro Produkt Jeder Eintrag in products[] muss product_id, product_name, variant_id, quantity und price enthalten.

Warum wir validieren

E-Commerce-Events unterstützen Features, die auf konsistente, vorhersagbare Daten angewiesen sind – darunter Umsatz-Tracking, der {% shopping_cart %} Liquid-Tag, der Warenkorb-Abbruch-Trigger und Reporting. Wenn Payloads vom Schema abweichen, erzeugen diese Features stille Ungenauigkeiten (falsche Umsatzsummen, fehlende Warenkörbe, fehlerhafte Trigger). Die Validierung erzwingt den Vertrag im Voraus, damit nachgelagerte Features vorhersagbar funktionieren.

Wenn die Validierung erfolgreich ist

Das Event wird als empfohlenes E-Commerce-Event mit der gesamten zugehörigen Nachbearbeitung verarbeitet. Siehe Event-Schemata für die vollständige Liste der durch jeden Event-Typ ausgelösten Verhaltensweisen.

Ein erfolgreiches Event überprüfen

Nachdem Sie ein Event gesendet haben, können Sie mit einer der folgenden Methoden bestätigen, dass es akzeptiert und korrekt verarbeitet wurde:

  • Event-Nutzerprotokoll: Öffnen Sie das Profil der Nutzer:in im Dashboard und überprüfen Sie die Aktivität. Empfohlene Events erscheinen mit ihrer vollständigen Eigenschafts-Payload, sodass Sie bestätigen können, dass das Event angekommen ist und die Werte mit dem übereinstimmen, was Sie gesendet haben.
  • Bericht zu angepassten Events: Gehen Sie zu Analytics > Custom Events, um aggregierte Zählungen jedes empfohlenen Events über die Zeit zu sehen. Dies ist nützlich, um zu bestätigen, dass der Produktions-Traffic wie erwartet fließt, wenn Ihre Integration live ist.
  • Testnutzer:innen: Markieren Sie eine Nutzer:in in Ihrem Entwicklungs-Workspace als Testnutzer:in und triggern Sie dann Events aus Ihrer Integration gegen diese Nutzer:in. Testnutzer:innen sind im Dashboard gekennzeichnet, was es einfach macht, das End-to-End-Verhalten zu isolieren und zu überprüfen.

Wenn die Validierung fehlschlägt

Das Event wird nicht als empfohlenes Event verarbeitet. Im Einzelnen:

  • Das Event wird vollständig verworfen. Ungültige empfohlene E-Commerce-Events landen nicht im Nutzerprofil, erscheinen nicht in Currents und sind nicht für die Segmentierung verfügbar.
  • Nachgelagerte Features für empfohlene Events werden nicht ausgeführt, darunter:
    • Umsatz-Tracking (Umsatz-Reporting, berechnete Nutzerfelder wie total_revenue)
    • Warenkorb-Objekt-Updates im Nutzerprofil
    • „Warenkorb-Aktualisierungs-Event durchführen“- oder „Bestellung aufgegeben“-Trigger in Canvas und Campaigns

Wie Fehler gemeldet werden, hängt vom Aufnahmepfad ab:

  • REST API (/users/track): Jedes ungültige Event wird im Fehler-Array der Antwort gemeldet. Jeder Eintrag gibt an, welches Event fehlgeschlagen ist (Index) und warum (Typ). Das message-Feld auf oberster Ebene zeigt weiterhin „success“ an, was nur bedeutet, dass Ihre Anfrage Braze erreicht hat – nicht, dass jedes Event gültig war. Prüfen Sie immer das Fehler-Array in der Antwort.
  • Braze SDKs: SDK-Aufrufe kehren sofort zurück und die Validierung läuft im Hintergrund, sodass Fehler nicht an Ihre App zurückgesendet werden. Um E-Commerce-Event-Validierungsfehler zu erfahren, achten Sie auf die Fehlerübersichts-E-Mail (siehe Fehler finden).

Beispiel einer API-Fehlerantwort

Der /users/track-Endpunkt gibt Fehler auf Feldebene zurück, die angeben, welche Eigenschaften fehlgeschlagen sind und warum. Beachten Sie, dass die message auf oberster Ebene möglicherweise "success" zurückgibt, da das Event in die Pipeline aufgenommen wurde; das errors-Array gibt an, welche Felder die Schema-Validierung nicht bestanden haben. Siehe das folgende Beispiel einer Fehlerantwort.

1
2
3
4

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

Fehler werden auch intern klassifiziert und für die Fehlerübersichts-E-Mail aggregiert:

Fehlertyp Bedeutung Beispiel
missing_property Ein erforderliches Feld fehlt. order_placed ohne order_id gesendet.
extra_property Ein Feld wurde hinzugefügt, das das Schema nicht definiert. Ein benutzerdefiniertes gift_wrapped-Feld auf der obersten Ebene von properties statt innerhalb von metadata.
unexpected_data_type Ein Feld hat den falschen Typ. total_value: "29.99" (String) statt 29.99 (Zahl).

Fehler finden

Braze sendet Ihren Workspace-Admins eine Zusammenfassung der Validierungsfehler empfohlener Events per E-Mail, damit Sie Integrationsprobleme identifizieren und beheben können, ohne jedes Event manuell überwachen zu müssen.

Die Zusammenfassungs-E-Mail enthält:

  • Gesamtfehleranzahl: Fehleranzahlen für den Berichtszeitraum.
  • Fehler nach Event: Eine Aufschlüsselung, wie viele Events für jeden empfohlenen Event-Typ fehlgeschlagen sind (z. B. ecommerce.cart_updated und ecommerce.order_placed). Nutzen Sie dies, um zu identifizieren, welche Events in Ihrer Integration zuerst Aufmerksamkeit benötigen.
  • Fehler nach Quelle: Eine Aufteilung zwischen API und SDK, damit Sie feststellen können, welche Integration die Fehler verursacht.

Wenn Sie diese E-Mails nicht erhalten oder die Empfängerliste überprüfen möchten, wenden Sie sich an Ihr Braze-Account-Team.

Fehler diagnostizieren und beheben

Wenn Sie eine Fehlerübersichts-E-Mail erhalten:

  1. Identifizieren Sie das fehlgeschlagene Event und die Quelle. Die E-Mail trennt Fehler nach Event-Name und Integrationsquelle (sdk versus rest_api), sodass Sie feststellen können, welche Integration die Korrektur benötigt. Wenn Sie mehrere Quellen haben, die dasselbe Event senden (z. B. Ihr Storefront-SDK und ein Backend-Webhook, die beide cart_updated senden), behandeln Sie diese unabhängig voneinander.
  2. Vergleichen Sie Ihre Payload mit dem Schema in Event-Schemata. Die meisten Fehler fallen in eines von drei Mustern:
    • missing_property: Ein erforderliches Feld fehlt. Lösung: Fügen Sie das erforderliche Feld hinzu.
    • extra_property: Ein benutzerdefiniertes Feld befindet sich auf der obersten Ebene von properties. Lösung: Verschieben Sie das benutzerdefinierte Feld in metadata (Event-Ebene) oder products[].metadata (pro Produkt).
    • unexpected_data_type: Ein Wert hat den falschen Typ (z. B. total_value als String gesendet). Lösung: Konvertieren Sie den Wert vor dem Senden.
  3. Testen Sie die korrigierte Payload in einem Entwicklungs-Workspace, bevor Sie sie in die Produktion ausrollen. Senden Sie ein bekanntes Test-Event für eine Testnutzer:in und überprüfen Sie dann das erwartete Verhalten des empfohlenen Events im Profil dieser Nutzer:in (z. B. ob das Warenkorb-Objekt aktualisiert wird, der Umsatz steigt oder der Warenkorb-Abbruch-Trigger ausgelöst wird).
  4. Überwachen Sie die nächste Fehler-E-Mail, um zu bestätigen, dass die Fehleranzahl für dieses Event, diese Quelle und diesen Typ auf null sinkt.

Die vollständigen Eigenschaftsanforderungen pro Event finden Sie unter Event-Schemata.
New Stuff!