Zum Inhalt springen

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 Zahl von Plattform-Features zur Verfügung.

Zu diesen Features gehören Canvas-Templates für Flows zu abgebrochenem Browsen, Warenkorb-Abbruch, abgebrochenem Checkout und Bestellbestätigung, E-Commerce-Reporting sowie berechnete Felder im Nutzerprofil für Total Revenue, Total Orders und Total Refunds. Außerdem können Sie mit Segmenterweiterungen Segmente mithilfe verschachtelter Filter nach Produkteigenschaften erstellen, Nachrichten zum Warenkorb-Abbruch mit dem Liquid-Tag {% shopping_cart %} personalisieren und Funktionen von BrazeAITM wie Predictive Events, Predictive Churn und Artikelempfehlungen sowie weitere Funktionen mit Daten versorgen.

Da diese Events einem definierten Schema folgen, kann jedes unterstützte Feature die strukturierten Daten lesen, ohne dass Sie Eigenschaften individuell abbilden oder einzelne Features konfigurieren müssen.

So funktionieren E-Commerce-Events

E-Commerce-Events sind angepasste Events mit vordefinierten Namen und Eigenschaftsschemas. Sie senden sie über das Braze SDK, den REST-API-Endpunkt /users/track, Cloud Data Ingestion (CDI) oder den CSV-Import. Braze validiert jedes Event bei der Aufnahme anhand seines Schemas. Ist die Validierung erfolgreich, wendet Braze automatisch eine für den jeweiligen Event-Typ spezifische Nachbearbeitung an, etwa die Berechnung von Umsatzfeldern und die Verwaltung des Warenkorbstatus in Nutzerprofilen.

E-Commerce-Events funktionieren überall dort, wo auch andere angepasste Events funktionieren: in Triggern und Filtern für ausgeführte angepasste Events, im Reporting für angepasste Events und mehr. Ihre Schema-Validierung ermöglicht jedoch zusätzliche Funktionen, darunter:

  • Trigger-Aktionen vom Typ „Places order“ in Kampagnen, Canvases, Aktionspfad-Schritten, Triggern für In-App-Nachrichten und beim Entfernen von Content-Cards
  • Berechnete E-Commerce-Felder im Nutzerprofil (Total Revenue, Total Orders, Total Refunds)
  • Verwaltung des Warenkorbstatus für Flows zum Warenkorb-Abbruch
  • Umfangreichere Daten für BrazeAITM-Features wie Predictive Events, Predictive Churn und Artikelempfehlungen

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

Benennung von Events

Event-Namen sind exakt, unterscheiden Groß- und Kleinschreibung und werden durch Punkte getrennt. Verwenden Sie immer das kanonische Format. Wenn ein Event-Name nicht exakt mit einem der sechs kanonischen Namen übereinstimmt, behandelt Braze ihn als standardmäßiges angepasstes Event, und es findet keine E-Commerce-Nachbearbeitung statt.

Sie können Events nicht anpassen oder umbenennen.

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

Event-Schemas

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

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

Für das clientseitige Logging verwenden ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started und ecommerce.order_placed die E-Commerce-Event-APIs des SDK, sofern verfügbar, während ecommerce.order_cancelled und ecommerce.order_refunded logCustomEvent verwenden.

Rückerstattungs- und Stornierungs-Events werden in der Regel von Ihrem Server über die Braze REST API gesendet, da sie meist vom Abschluss serverseitiger Logik abhängen, etwa Ihres Rückerstattungsprozesses. Plattformspezifische Implementierungsbeispiele finden Sie unter E-Commerce-Events über das Braze SDK protokollieren.

Triggern Sie dieses Event, wenn Nutzer:innen eine Produktdetailseite aufrufen. Dieses Event ist mit den Katalog-Features von Braze für Benachrichtigungen bei Wiederverfügbarkeit und Benachrichtigungen bei Preissenkungen kompatibel.

Clientseitige Implementierung

Verwenden Sie die E-Commerce-Event-APIs des SDK, 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 (zum Beispiel SKU oder Artikel-ID).
product_name String Ja Anzeigename des Produkts.
variant_id String Ja Bezeichner der Produktvariante (zum Beispiel shirt_medium_blue).
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite mit weiteren Details.
price Float Ja Stückpreis der Variante zum Zeitpunkt des Aufrufs.
currency String Ja Dreistelliger ISO-4217-Code (zum Beispiel USD oder EUR).
source String Ja Quelle, aus der das Event stammt (zum Beispiel web, ios oder android).
type String-Array Nein Erforderlich, um die Katalog-Trigger-Features von Braze für Benachrichtigungen bei Wiederverfügbarkeit und Preissenkungen zu nutzen. Zulässige Werte: "price_drop", "back_in_stock".
catalog_name String Nein Der Katalog, zu dem ein aus diesem Event erstelltes Abo für Wiederverfügbarkeit oder Preissenkungen gehört. Wenn diese Eigenschaft fehlt, wird der Fallback-Katalog des Workspace verwendet. Muss eine Eigenschaft der obersten Ebene sein; ein innerhalb von metadata verschachteltes catalog_name wird ignoriert.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel category oder brand).

REST-API-Beispiel




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

Triggern Sie dieses Event jedes Mal, wenn sich der Inhalt des Warenkorbs von Nutzer:innen ändert.

Clientseitige Implementierung

Verwenden Sie die E-Commerce-Event-APIs des SDK, 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ändiges Ersetzen des Warenkorbs: Lassen Sie action weg oder setzen Sie action auf replace. Geben Sie in products alle Positionen mit absoluten Mengen an (Gesamtzahl der Einheiten pro Variante im Warenkorb). Sie müssen total_value angeben.
  • Inkrementelle Warenkorb-Updates: Setzen Sie action auf add oder remove. Geben Sie nur die Positionen an, die sich geändert haben. Jede quantity ist die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten, nicht die Gesamtmenge im Warenkorb.
    • Bei add erhöht Braze die Menge der Position oder fügt eine neue Position hinzu. Bei remove verringert Braze die Menge der Position und entfernt sie, wenn die Menge 0 erreicht.
    • Bei add und remove ist total_value optional und wird nicht im Warenkorb gespeichert. Bei einem Warenkorb, der nur mit add oder remove aktualisiert wurde, gibt das Tag {% shopping_cart %} stattdessen die Summe aus dem price jedes Produkts multipliziert mit seiner quantity zurück.

Um Messaging über dieses Event zu triggern, verwenden Sie den Trigger Perform Cart Updated Event in Canvas und Kampagnen. Dieser Trigger enthält eine spezielle Verarbeitung, die verhindert, dass der Warenkorb im Shopping-Funnel weiter voranschreitet.

Der Warenkorb erstellt im Nutzerprofil ein Warenkorb-Mapping-Objekt, auf dem das Liquid-Tag {% shopping_cart %} basiert. Der Warenkorb läuft nach 30 Tagen ohne Update ab und wird entfernt, wenn das nächste E-Commerce-Event der Nutzer:in verarbeitet wird. Wenn zwei Nutzerprofile zusammengeführt werden, behält Braze beide Warenkörbe bei.

Warenkorb-ID nach Checkout oder Bestellung

Nachdem Braze ecommerce.checkout_started oder ecommerce.order_placed für eine cart_id empfangen hat, wird dieser Warenkorb nicht mehr als abgebrochen behandelt:

  • Künftige ecommerce.cart_updated-Events mit derselben cart_id triggern Perform Cart Updated Event nicht
  • Das Tag {% shopping_cart %} bricht standardmäßig ab
  • Nach ecommerce.order_placed werden die Produkte des Warenkorbs gelöscht, und spätere Warenkorb-Updates für diese cart_id werden ignoriert, bis der Warenkorb abläuft

Generieren Sie eine neue cart_id, wenn Käufer:innen einen neuen Warenkorb beginnen.

Event-Eigenschaften

Eigenschaft Datentyp Erforderlich Beschreibung
cart_id String Ja Eindeutiger Bezeichner für den Warenkorb. Wird von Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in gemeinsam genutzt. Verwenden Sie eine cart_id nach ecommerce.checkout_started oder ecommerce.order_placed nicht erneut; siehe Warenkorb-ID nach Checkout oder Bestellung.
action String Nein add (Menge erhöhen oder Position hinzufügen), remove (Menge verringern; Position wird bei 0 entfernt) oder replace (vollständiges Ersetzen des Warenkorbs, entspricht dem Weglassen von action).
total_value Float Bedingt Erforderlich, wenn action fehlt oder replace ist; wird als Warenkorbsumme gespeichert. Optional, wenn action add oder remove ist.

Wenn action add oder remove ist, wird der Wert nicht im Warenkorb gespeichert und löscht keine zuvor gespeicherte Summe. Wird ein Warenkorb nur mit add oder remove aktualisiert, wird kein total_value gespeichert, und das Tag {% shopping_cart %} summiert den price jedes Produkts multipliziert mit seiner quantity.
subtotal_value Float Nein Zwischensumme des Warenkorbs (nach Rabatt, vor Steuern/Versand). Wird nicht im Warenkorb gespeichert und ist nicht über das Liquid-Tag {% shopping_cart %} verfügbar.
tax Float Nein Auf den Warenkorb angewendete Gesamtsteuer. Wird nicht im Warenkorb gespeichert und ist nicht über das Liquid-Tag {% shopping_cart %} verfügbar.
shipping Float Nein Gesamte Versandkosten für den Warenkorb. Wird nicht im Warenkorb gespeichert und ist nicht über das Liquid-Tag {% shopping_cart %} verfügbar.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Positionen für dieses Update. Beim vollständigen Ersetzen (kein action oder replace) geben Sie den gesamten Warenkorb mit absoluten Mengen an. Bei add oder remove geben Sie nur geänderte Positionen an; siehe Produkteigenschaften.
source String Ja Quelle, aus der das Event stammt.
metadata Object 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Beim vollständigen Ersetzen (kein action oder replace) die Einheiten dieser Position im Warenkorb. Bei add oder remove die Anzahl der hinzuzufügenden oder zu entfernenden Einheiten.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

Triggern Sie dieses Event, wenn Nutzer:innen den Checkout-Prozess starten (zum Beispiel „Checkout“ auswählen oder auf der Checkout-Seite landen).

Clientseitige Implementierung

Verwenden Sie die E-Commerce-Event-APIs des SDK, 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 Bezeichner des Warenkorbs. Wird von Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in gemeinsam genutzt.
total_value Float Ja Gesamter Geldwert des Checkouts.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Auf den Checkout angewendete Gesamtsteuer.
shipping Float Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
products Array Ja Artikel im Checkout. Siehe Untertabelle der Produkteigenschaften.
source String Ja Quelle, aus der das Event stammt.
metadata Object 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (z. B. Farbe, Größe).

REST-API-Beispiel




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

Triggern Sie dieses Event, wenn eine Bestellung erfolgreich abgeschlossen oder die Zahlung bestätigt wurde.

Clientseitige Implementierung

Verwenden Sie die E-Commerce-Event-APIs des SDK, 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 Bezeichner des Warenkorbs. Wird von Warenkorb-, Checkout- und Bestell-Events für das Warenkorb-Mapping der Nutzer:in gemeinsam genutzt.
total_value Float Ja Gesamter Geldwert der Bestellung.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Auf die Bestellung angewendete Gesamtsteuer.
shipping Float Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Float Nein Gesamtbetrag der auf die Bestellung angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der angewendeten Rabatte.
products Array Ja Artikel in der Bestellung. Siehe Untertabelle der Produkteigenschaften.
source String Ja Quelle, aus der das Event stammt.
metadata Object 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiel




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

Triggern Sie dieses Event, 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 Float Ja Gesamter Geldwert der stornierten Bestellung. Muss ≥ 0 sein – senden Sie den absoluten Betrag; Braze übernimmt die Verringerung.
subtotal_value Float Nein Zwischensumme (nach Rabatt, vor Steuern/Versand).
tax Float Nein Auf die Bestellung angewendete Gesamtsteuer.
shipping Float Nein Gesamte Versandkosten.
currency String Ja Dreistelliger ISO-4217-Code.
total_discounts Float Nein Gesamtbetrag der auf die Bestellung angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der angewendeten Rabatte.
cancel_reason String Ja Grund für die Stornierung der Bestellung.
products Array Ja Artikel in der stornierten Bestellung. Siehe Untertabelle der Produkteigenschaften.
source String Ja Quelle, aus der das Event stammt.
metadata Object 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiel




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

Triggern Sie dieses Event, wenn eine vollständige oder teilweise Rückerstattung 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 Float Ja Gesamter Geldwert der Rückerstattung. 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 Float Nein Gesamtbetrag der ursprünglich angewendeten Rabatte.
discounts Array Nein Detaillierte Liste der Rabatte.
products Array Ja Zurückerstattete Artikel. Siehe Untertabelle der Produkteigenschaften.
source String Ja Quelle, aus der das Event stammt.
metadata Object 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 Bezeichner der Variante.
image_url String Nein URL des Produktbilds.
product_url String Nein URL zur Produktseite.
quantity Integer Ja Anzahl der Einheiten im Warenkorb.
price Float Ja Stückpreis der Variante.
metadata Object Nein Flexible Schlüssel-Wert-Paare (zum Beispiel color oder size).

REST-API-Beispiele




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

Nachbearbeitung von E-Commerce-Events

Wenn Sie ein E-Commerce-Event senden, validiert Braze es anhand des erwarteten Schemas für diesen Event-Namen.

Die folgende Tabelle fasst zusammen, was Braze bei erfolgreicher Validierung für jedes Event automatisch ausführt. Was bei einer fehlgeschlagenen Validierung passiert, erfahren Sie unter Event-Validierung und Fehlerbehebung.

Event Was Braze automatisch ausführt
ecommerce.order_placed Erhöht im Nutzerprofil Total Revenue um total_value und Total Orders um 1.
ecommerce.order_cancelled Verringert Total Orders um 1.
ecommerce.order_refunded Verringert Total Revenue um total_value und erhöht Total Refund Value.
ecommerce.cart_updated Erstellt oder aktualisiert das Warenkorb-Mapping-Objekt im Nutzerprofil (vollständige Warenkorb-Payloads oder inkrementelle Warenkorb-Updates mit optionaler 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, Triggern und BrazeAITM-Features (wie Artikelempfehlungen).
ecommerce.checkout_started Keine Änderungen am Nutzerprofil. Verfügbar für Segmentierung und Triggern (zum Beispiel Flows zu abgebrochenem Checkout).

Implementierungsdetails

Datenpunkte und Abrechnung

E-Commerce-Events verbrauchen keine Datenpunkte. Sie können sie protokollieren, ohne dass sich dies auf Ihre Datenpunkt-Nutzung auswirkt.

Größenlimit für Events

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

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

Umgang mit Währungen

Braze rechnet Währungswerte, die nicht in USD angegeben sind, automatisch zum Wechselkurs des Tages, an dem das Event gemeldet wird, in USD um. Dieser umgerechnete Wert erscheint in den Umsatzmetriken.

Feld „source“

Die Eigenschaft „source“ ist ein erforderlicher String, der angibt, woher das Event stammt, zum Beispiel shopify, in-store POS oder custom_api. So können Sie Integrationsquellen unterscheiden, wenn Sie Daten in Currents-Exporten analysieren oder Validierungsprobleme beheben.

Flexible Metadaten

Sowohl das Metadaten-Objekt auf Event-Ebene als auch das auf Produktebene akzeptieren beliebige Schlüssel-Wert-Paare. So können Sie angepasste Dimensionen hinzufügen, ohne das Kernschema zu ändern. Gängige Beispiele sind order_status_url, gift_wrapped, loyalty_points_earned oder warehouse_id. Diese Eigenschaften stehen in der Liquid-Personalisierung, in Currents-Exporten und für die Segmentierung über Segmenterweiterungen zur Verfügung.

Event-Validierung und Fehlerbehebung

Wenn Sie ein empfohlenes E-Commerce-Event über /users/track oder ein Braze SDK senden, validiert Braze den Payload bei der Verarbeitung des empfohlenen Events anhand des JSON-Schemas des Events. Die Validierung läuft automatisch für jedes Event, dessen Name exakt mit einem empfohlenen Event übereinstimmt (zum Beispiel ecommerce.order_placed oder ecommerce.cart_updated).

Was wir validieren

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

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 Angepasste Felder unter den Eigenschaften führen zu einem Fehler. Verwenden Sie stattdessen das Objekt metadata.
Werteinschränkungen Geldbetragsfelder müssen ≥ 0 sein. currency muss ein gültiger ISO-4217-String sein.
Felder pro Produkt Jeder Artikel in products[] muss product_id, product_name, variant_id, quantity und price enthalten.

Warum wir validieren

E-Commerce-Events treiben Features an, die auf konsistente, vorhersehbare Daten angewiesen sind – darunter Umsatz-Tracking, der Liquid-Tag {% shopping_cart %}, der Trigger für Warenkorb-Abbrüche und das Reporting. Weichen Payloads vom Schema ab, liefern diese Features unbemerkt ungenaue Ergebnisse (falsche Umsatzsummen, fehlende Warenkörbe, defekte Trigger). Die Validierung setzt den Vertrag von vornherein durch, sodass sich nachgelagerte Features vorhersehbar verhalten.

Wenn die Validierung erfolgreich ist

Das Event wird als empfohlenes E-Commerce-Event mit der gesamten zugehörigen Nachverarbeitung verarbeitet. Unter Empfohlene E-Commerce-Events finden Sie die vollständige Liste der Verhaltensweisen, die durch jeden Event-Typ ausgelöst werden.

Erfolgreiches Event überprüfen

Nachdem Sie ein Event gesendet haben, können Sie auf eine der folgenden Arten bestätigen, dass es akzeptiert und korrekt verarbeitet wurde:

  • Event-Nutzerprotokoll: Öffnen Sie das Profil der Nutzer:in im Dashboard und überprüfen Sie deren Aktivität. Empfohlene Events erscheinen mit ihrem vollständigen Eigenschafts-Payload, sodass Sie bestätigen können, dass das Event angekommen ist und die Werte mit den gesendeten übereinstimmen.
  • Bericht über angepasste Events: Gehen Sie zu Analytics > Bericht über angepasste Events, um aggregierte Zählungen jedes empfohlenen Events im Zeitverlauf zu sehen. Das ist hilfreich, um zu bestätigen, dass der Produktions-Traffic wie erwartet fließt, sobald 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 für diese Nutzer:in. Testnutzer:innen werden im Dashboard gekennzeichnet, sodass Sie das End-to-End-Verhalten leicht isolieren und untersuchen können.

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 stehen nicht für die Segmentierung zur Verfügung.
  • Nachgelagerte Features für empfohlene Events werden nicht ausgeführt, darunter:
    • Umsatz-Tracking (Umsatz-Reporting, berechnete Nutzerfelder wie total_revenue)
    • Updates des Warenkorb-Objekts im Nutzerprofil
    • Update Cart- oder Place Order-Trigger in Canvas und Campaigns

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

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

Beispiel für eine API-Fehlerantwort

Der Endpunkt /users/track gibt Fehler auf Feldebene zurück, die angeben, welche Eigenschaften fehlgeschlagen sind und warum. Beachten Sie, dass message auf oberster Ebene "success" zurückgeben kann, weil das Event in die Pipeline aufgenommen wurde. Das Array errors zeigt Ihnen, welche Felder die Schema-Validierung nicht bestanden haben. Ein Beispiel finden Sie in der folgenden Fehlerantwort.




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

Fehler werden außerdem intern klassifiziert und für die E-Mail mit der Fehlerzusammenfassung aggregiert:

Fehlertyp Bedeutung Beispiel
missing_property Ein erforderliches Feld fehlt. order_placed wurde ohne order_id gesendet.
extra_property Es wurde ein Feld hinzugefügt, das im Schema nicht definiert ist. Ein angepasstes Feld gift_wrapped auf oberster 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 den Admins Ihres Workspace per E-Mail eine Zusammenfassung der Validierungsfehler bei empfohlenen Events, damit Sie Integrationsprobleme erkennen und beheben können, ohne jedes Event manuell überwachen zu müssen.

Die Zusammenfassungs-E-Mail enthält:

  • Gesamtzahl der Fehler: Fehlerzahlen für den Berichtszeitraum.
  • Fehler nach Event: Eine Aufschlüsselung, wie viele Events für jeden Typ empfohlener Events fehlgeschlagen sind (zum Beispiel ecommerce.cart_updated und ecommerce.order_placed). Damit erkennen Sie, welche Events in Ihrer Integration zuerst Aufmerksamkeit benötigen.
  • Fehler nach Quelle: Eine Aufteilung nach API und SDK, damit Sie genau bestimmen 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 E-Mail mit einer Fehlerzusammenfassung erhalten:

  1. Ermitteln Sie das fehlerhafte Event und die Quelle. Die E-Mail trennt Fehler nach Event-Name und Integrationsquelle (sdk oder rest_api), sodass Sie genau bestimmen können, welche Integration korrigiert werden muss. Wenn mehrere Quellen dasselbe Event senden (zum Beispiel senden sowohl Ihr Storefront-SDK als auch ein Backend-Webhook cart_updated), bearbeiten Sie diese unabhängig voneinander.
  2. Vergleichen Sie Ihren Payload mit dem Schema unter Event-Schemas. Die meisten Fehler fallen in eines von drei Mustern:
    • missing_property: Ein erforderliches Feld fehlt. Fügen Sie zur Behebung das erforderliche Feld hinzu.
    • extra_property: Ein angepasstes Feld befindet sich auf oberster Ebene von properties. Verschieben Sie zur Behebung das angepasste Feld in metadata (Event-Ebene) oder products[].metadata (pro Produkt).
    • unexpected_data_type: Ein Wert hat den falschen Typ (zum Beispiel wird total_value als String gesendet). Konvertieren Sie zur Behebung den Wert vor dem Senden.
  3. Testen Sie den korrigierten Payload in einem Entwicklungs-Workspace, bevor Sie ihn in der 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 (zum Beispiel, ob das Warenkorb-Objekt aktualisiert wird, der Umsatz steigt oder der Trigger für Warenkorb-Abbrüche ausgelöst wird).
  4. Beobachten Sie die nächste Fehler-E-Mail, um zu bestätigen, dass die Fehlerzahl für dieses Event, diese Quelle und diesen Typ auf null sinkt.

Die vollständigen Anforderungen an Eigenschaften pro Event finden Sie unter Event-Schemas.

Dokumentation für die Braze-Kundenengagement-Plattform.

Ressourcen
Rechtliches
Unternehmen
© 2026 Braze, Inc. Alle Rechte vorbehalten.
Braze-Status wird geprüft
New Stuff!