このページはAIにより自動翻訳されており、不正確な内容が含まれている可能性があります。翻訳の誤りを報告するには、ページ右側の目次の下にあるフィードバックをご利用ください。

推奨イベント

推奨イベントは、定義済みのJSONスキーマを持つ標準化されたカスタムイベントを送信するフレームワーク上に構築されています。推奨イベントを送信すると、Brazeは取り込み時にスキーマに対してバリデーションを行い、自動フィールド計算やカート管理など、汎用カスタムイベントでは適用されない特別な後処理を実行します。特定の業界向けイベントセットについては、キャンペーンやキャンバスの専用アクションベーストリガーなど、Brazeが特別な処理をサポートする場合があります。

eコマース推奨イベント

eコマース推奨イベントは、購入ジャーニーの6つのステップをカバーしています。product_viewed、cart_updated、checkout_started、order_placed、order_cancelled、order_refundedです。これらのイベントが正常に送信されると、Brazeはデータを検証し、拡大し続けるプラットフォーム機能で利用できるようにします。

対象となる機能には、閲覧放棄、カート放棄、チェックアウト放棄、注文確認フロー向けのキャンバステンプレート、eコマースレポート、合計収益、合計注文数、合計返金額の計算済みユーザープロファイルフィールドがあります。また、セグメントエクステンションによるネストされた製品プロパティのフィルタリングを使用してセグメントを作成したり、{% shopping_cart %} Liquidタグでカート放棄メッセージをパーソナライズしたりできます。さらに、予測イベント、解約予測、アイテムレコメンデーションなどのBrazeAI^TM機能にもデータを提供できます。

これらのイベントは定義済みのスキーマに従っているため、サポートされている各機能は、カスタムプロパティのマッピングや機能ごとの設定を行わなくても構造化データを読み取ることができます。

重要

レガシーの購入イベントはメンテナンスモードに移行します。既存のBrazeのお客様は、レガシーの購入イベントを引き続き使用できます。購入イベントは引き続き期待どおりに動作しますが、今後はeコマース推奨イベントを基盤として新しい機能が構築されます。Brazeは、サポート終了日が設定されるかなり前に事前通知を行います。新規のBrazeのお客様は、eコマース推奨イベントを使用してください。レガシーの購入イベントは利用できません。

eコマースイベントの仕組み

eコマースイベントは、事前定義された名前とプロパティスキーマを持つカスタムイベントです。これらのイベントは、Braze SDK、/users/track REST APIエンドポイント、クラウドデータ取り込み (CDI)、またはCSVインポートを使用して送信します。Brazeは取り込み時に各イベントをスキーマに照らして検証します。検証に合格すると、Brazeはそのイベントタイプに固有の後処理 (収益フィールドの計算やユーザープロファイル上のカート状態の管理など) を自動的に適用します。

eコマースイベントは、他のカスタムイベントが使用できる場所であればどこでも使用できます。たとえば、実行されたカスタムイベントのトリガーやフィルター、カスタムイベントレポートなどです。さらに、スキーマ検証によって次のような追加機能も利用できるようになります。

キャンペーン、キャンバス、アクションパスステップ、アプリ内メッセージのトリガー、Content Cardの削除における「注文する」トリガーアクション
計算済みのeコマースユーザープロファイルフィールド (合計収益、合計注文数、合計返金額)
カート放棄フローのためのカート状態管理
予測イベント、解約予測、アイテムレコメンデーションなどのBrazeAI^TM機能向けのより充実したデータ

また、プラットフォームがカスタムイベントをサポートしている場所であれば、どこでもeコマースイベントを名前で参照できます。たとえば、ecommerce.product_viewedイベントでアクションベースのキャンペーンをトリガーしたり、ecommerce.checkout_startedイベントでフィルタリングするセグメントを作成したり、Currentsを通じてecommerce.order_placedイベントをエクスポートしたりできます。

イベントの命名

イベント名は完全一致で、大文字と小文字が区別され、ドットで区切られます。常に正規の形式を使用してください。イベント名が6つの正規名のいずれとも完全に一致しない場合、Brazeはそのイベントを標準のカスタムイベントとして扱い、eコマースの後処理は行われません。

イベントをカスタマイズしたり名前を変更したりすることはできません。

正しい例: ecommerce.order_placed
誤った例: order.placed、eCommerce_order_placed、Order_Placed

イベントスキーマ

6つのeコマース推奨イベントは、購入ジャーニーの各段階に対応しています。ユーザーが対応するアクションを完了した時点で、各イベントを送信してください。

6つのeコマース推奨イベント (product_viewed、cart_updated、checkout_started、order_placed、order_cancelled、order_refunded) を通過するユーザージャーニーの図。

ヒント

以下のタブの例は、各イベントのREST APIペイロードを示しています。

クライアント側のログ記録では、ecommerce.product_viewed、ecommerce.cart_updated、ecommerce.checkout_started、ecommerce.order_placedは利用可能な場合はSDKのeコマースイベントAPIを使用し、ecommerce.order_cancelledとecommerce.order_refundedはlogCustomEventを使用します。

返金およびキャンセルのイベントは、返金フローなどのサーバー側ロジックの完了に依存する傾向があるため、通常はBraze REST APIを通じてサーバーから送信します。プラットフォーム別の実装例については、Braze SDKを通じてeコマースイベントを記録するを参照してください。

ユーザーが製品詳細ページを閲覧したときにトリガーします。このイベントは、Brazeカタログの在庫復活通知および値下げ通知と互換性があります。

クライアント側の実装

利用可能な場合は、SDKのeコマースイベントAPIを使用してください。プラットフォーム別の実装例については、Braze SDKを通じてeコマースイベントを記録するを参照してください。

イベントプロパティ

プロパティ名	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子 (SKUやアイテムIDなど)。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	製品バリアントの識別子 (`shirt_medium_blue`など)。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	詳細を確認できる製品ページのURL。
`price`	浮動小数点数	はい	閲覧時点でのバリアントの単価。
`currency`	文字列	はい	3文字のISO 4217コード (`USD`や`EUR`など)。
`source`	文字列	はい	イベントの発生元 (`web`、`ios`、`android`など)。
`type`	文字列の配列	いいえ	在庫復活アラートおよび値下げアラートでBrazeカタログのトリガー機能を使用する場合に必須です。使用できる値: `"price_drop"`、`"back_in_stock"`。
`catalog_name`	文字列	いいえ	このイベントから作成された在庫復活または値下げの購読が属するカタログ。省略した場合は、ワークスペースのフォールバックカタログが使用されます。トップレベルのプロパティである必要があります。`metadata`内にネストされた`catalog_name`は無視されます。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (`category`や`brand`など)。

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

ユーザーのカートの内容が変更されるたびにトリガーします。

クライアント側の実装

このイベントは、次の2つの方法のいずれかで送信できます。

カート全体の置換: actionを省略するか、actionをreplaceに設定します。productsには、絶対数量 (カート内のバリアントごとの合計数) を含むすべての明細を含めます。total_valueを含める必要があります。
カートの増分更新: actionをaddまたはremoveに設定します。変更された明細のみを含めます。各quantityは追加または削除する数量であり、カート内の合計数量ではありません。
- addの場合、Brazeは明細の数量を増やすか、新しい明細を追加します。removeの場合、Brazeは明細の数量を減らし、数量が0になると明細を削除します。
- addおよびremoveの場合、total_valueは任意で、カートには保存されません。addまたはremoveのみで更新されたカートの場合、{% shopping_cart %}タグは代わりに各製品のpriceにquantityを掛けた値の合計を返します。

警告

1つのカートには、増分更新 (addまたはremove) と全体置換 (actionなし、またはreplace) のどちらか一方を使用してください。同じcart_idに両方の方法を混在させることは推奨されず、Braze内でカートの状態が不整合になる可能性があります。

このイベントからメッセージングをトリガーするには、キャンバスおよびキャンペーンでカート更新イベントを実行トリガーを使用してください。このトリガーには、カートがショッピングファネルを進むのを止めるための特別な処理が含まれています。

カートはユーザープロファイル上にカートのマッピングオブジェクトを作成し、これが{% shopping_cart %} Liquidタグを支えます。カートは30日間更新がないと期限切れになり、そのユーザーの次のeコマースイベントが処理されたときに削除されます。2つのユーザープロファイルがマージされた場合、Brazeは両方のカートを保持します。

チェックアウトまたは注文後のカートID

Brazeがcart_idに対してecommerce.checkout_startedまたはecommerce.order_placedを受信すると、そのカートは放棄されたものとして扱われなくなります。

同じcart_idを持つ以降のecommerce.cart_updatedイベントは、カート更新イベントを実行をトリガーしません
{% shopping_cart %}タグはデフォルトで中止されます
ecommerce.order_placedの後は、カートの製品がクリアされ、カートが期限切れになるまで、そのcart_idに対する以降のカート更新は無視されます

買い物客が新しいカートを開始したときは、新しいcart_idを生成してください。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`cart_id`	文字列	はい	カートの一意の識別子。ユーザーのカートマッピングのために、カート、チェックアウト、注文の各イベント間で共有されます。`ecommerce.checkout_started`または`ecommerce.order_placed`の後に`cart_id`を再利用しないでください。詳しくはチェックアウトまたは注文後のカートIDを参照してください。
`action`	文字列	いいえ	`add` (数量を増やすか明細を追加)、`remove` (数量を減らし、`0`で明細を削除)、または`replace` (カート全体の置換。`action`を省略した場合と同じ)。
`total_value`	浮動小数点数	条件付き	`action`を省略した場合または`replace`の場合は必須で、カートの合計として保存されます。`action`が`add`または`remove`の場合は任意です。 `action`が`add`または`remove`の場合、この値はカートに保存されず、以前に保存された合計もクリアされません。`add`または`remove`のみで更新されたカートには`total_value`が保存されず、`{% shopping_cart %}`タグは各製品の`price`に`quantity`を掛けた値を合計します。
`subtotal_value`	浮動小数点数	いいえ	カートの小計 (割引後、税金・送料前)。カートには保存されず、`{% shopping_cart %}` Liquidタグでも利用できません。
`tax`	浮動小数点数	いいえ	カートに適用された税金の合計。カートには保存されず、`{% shopping_cart %}` Liquidタグでも利用できません。
`shipping`	浮動小数点数	いいえ	カートの送料の合計。カートには保存されず、`{% shopping_cart %}` Liquidタグでも利用できません。
`currency`	文字列	はい	3文字のISO 4217コード。
`products`	配列	はい	この更新の明細。全体置換 (`action`なし、または`replace`) の場合は、絶対数量でカート全体を含めます。`add`または`remove`の場合は、変更された明細のみを含めます。製品プロパティを参照してください。
`source`	文字列	はい	イベントの発生元。
`metadata`	オブジェクト	いいえ	追加のイベントレベルデータ用の柔軟なキーと値のペア。

製品プロパティ (`products[]`)

プロパティ	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	バリアントの識別子。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	製品ページのURL。
`quantity`	整数	はい	全体置換 (`action`なし、または`replace`) の場合は、この明細のカート内の数量。`add`または`remove`の場合は、追加または削除する数量。
`price`	浮動小数点数	はい	バリアントの単価。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (`color`や`size`など)。

ユーザーがチェックアウトフローを開始したとき (「チェックアウト」を選択した、チェックアウトページに到達したなど) にトリガーします。

クライアント側の実装

イベントプロパティ

プロパティ	タイプ	必須	説明
checkout_id	文字列	はい	チェックアウトセッションの一意の識別子。
cart_id	文字列	いいえ	カートの識別子。ユーザーのカートマッピングのために、カート、チェックアウト、注文の各イベント間で共有されます。
total_value	浮動小数点数	はい	チェックアウトの合計金額。
subtotal_value	浮動小数点数	いいえ	小計 (割引後、税金・送料前)。
tax	浮動小数点数	いいえ	チェックアウトに適用された税金の合計。
shipping	浮動小数点数	いいえ	送料の合計。
currency	文字列	はい	3文字のISO 4217コード。
products	配列	はい	チェックアウト対象のアイテム。製品プロパティのサブテーブルを参照してください。
source	文字列	はい	イベントの発生元。
metadata	オブジェクト	いいえ	柔軟なキーと値のペア。認識されるサブプロパティ: `checkout_url` (文字列)

製品プロパティ (`products[]`)

プロパティ	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	バリアントの識別子。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	製品ページのURL。
`quantity`	整数	はい	カート内の数量。
`price`	浮動小数点数	はい	バリアントの単価。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (色、サイズなど)。

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

注文が正常に完了したとき、または支払いが確認されたときにトリガーします。

クライアント側の実装

重要

このイベントは主要な収益ドライバーです。ユーザープロファイル上で、total_revenueをtotal_valueの値だけ増やし、total_ordersを1増やします。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`order_id`	文字列	はい	注文の一意の識別子。
`cart_id`	文字列	いいえ	カートの識別子。ユーザーのカートマッピングのために、カート、チェックアウト、注文の各イベント間で共有されます。
`total_value`	浮動小数点数	はい	注文の合計金額。
`subtotal_value`	浮動小数点数	いいえ	小計 (割引後、税金・送料前)。
`tax`	浮動小数点数	いいえ	注文に適用された税金の合計。
`shipping`	浮動小数点数	いいえ	送料の合計。
`currency`	文字列	はい	3文字のISO 4217コード。
`total_discounts`	浮動小数点数	いいえ	注文に適用された割引の合計額。
`discounts`	配列	いいえ	適用された割引の詳細リスト。
`products`	配列	はい	注文内のアイテム。製品プロパティのサブテーブルを参照してください。
`source`	文字列	はい	イベントの発生元。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア。認識されるサブプロパティ: `order_status_url` (文字列)

製品プロパティ (`products[]`)

プロパティ	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	バリアントの識別子。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	製品ページのURL。
`quantity`	整数	はい	カート内の数量。
`price`	浮動小数点数	はい	バリアントの単価。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (`color`や`size`など)。

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

注文がキャンセルされたときにトリガーします。

クライアント側の実装

logCustomEventを使用してください。プラットフォーム別の実装例については、Braze SDKを通じてeコマースイベントを記録するを参照してください。

重要

このイベントは、ユーザープロファイル上のtotal_ordersを1減らします。total_revenueには影響しません。収益を調整するにはorder_refundedを使用してください。

イベントプロパティ

プロパティ	タイプ	必須	説明
`order_id`	文字列	はい	注文の一意の識別子。
`total_value`	浮動小数点数	はい	キャンセルされる注文の合計金額。0以上である必要があります。絶対額を送信してください。減算はBrazeが処理します。
`subtotal_value`	浮動小数点数	いいえ	小計 (割引後、税金・送料前)。
`tax`	浮動小数点数	いいえ	注文に適用された税金の合計。
`shipping`	浮動小数点数	いいえ	送料の合計。
`currency`	文字列	はい	3文字のISO 4217コード。
`total_discounts`	浮動小数点数	いいえ	注文に適用された割引の合計額。
`discounts`	配列	いいえ	適用された割引の詳細リスト。
`cancel_reason`	文字列	はい	注文がキャンセルされた理由。
`products`	配列	はい	キャンセルされた注文内のアイテム。製品プロパティのサブテーブルを参照してください。
`source`	文字列	はい	イベントの発生元。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア。認識されるサブプロパティ: `order_status_url` (文字列)

製品プロパティ (`products[]`)

プロパティ	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	バリアントの識別子。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	製品ページのURL。
`quantity`	整数	はい	カート内の数量。
`price`	浮動小数点数	はい	バリアントの単価。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (`color`や`size`など)。

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

全額または一部の返金が行われたときにトリガーします。

クライアント側の実装

logCustomEventを使用してください。プラットフォーム別の実装例については、Braze SDKを通じてeコマースイベントを記録するを参照してください。

重要

このイベントは、ユーザープロファイル上でtotal_revenueをtotal_valueの値だけ減らし、total_refundsを増やします。一部返金の場合は、total_valueを元の注文合計ではなく返金額のみに設定してください。

イベントプロパティ

プロパティ	データタイプ	必須	説明
`order_id`	文字列	はい	元の注文の一意の識別子。
`total_value`	浮動小数点数	はい	返金の合計金額。0以上である必要があります。絶対額を送信してください。total_refundsへの加算はBrazeが処理します。
`currency`	文字列	はい	3文字のISO 4217コード。
`total_discounts`	浮動小数点数	いいえ	元の注文に適用された割引の合計額。
`discounts`	配列	いいえ	割引の詳細リスト。
`products`	配列	はい	返金対象のアイテム。製品プロパティのサブテーブルを参照してください。
`source`	文字列	はい	イベントの発生元。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア。認識されるサブプロパティ: `order_status_url` (文字列)。

製品プロパティ (`products[]`)

プロパティ	データタイプ	必須	説明
`product_id`	文字列	はい	一意の製品識別子。
`product_name`	文字列	はい	製品の表示名。
`variant_id`	文字列	はい	バリアントの識別子。
`image_url`	文字列	いいえ	製品画像のURL。
`product_url`	文字列	いいえ	製品ページのURL。
`quantity`	整数	はい	カート内の数量。
`price`	浮動小数点数	はい	バリアントの単価。
`metadata`	オブジェクト	いいえ	柔軟なキーと値のペア (`color`や`size`など)。

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

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

eコマースイベントの後処理

eコマースイベントを送信すると、Brazeはそのイベント名に対して想定されるスキーマに照らしてイベントを検証します。

次の表は、検証に合格した場合にBrazeが各イベントに対して自動的に行う処理をまとめたものです。検証に失敗した場合の動作については、イベントのバリデーションとトラブルシューティングを参照してください。

イベント	Brazeが自動的に行う処理
`ecommerce.order_placed`	ユーザープロファイル上で、合計収益を`total_value`だけ増やし、合計注文数を1増やします。
`ecommerce.order_cancelled`	合計注文数を1減らします。
`ecommerce.order_refunded`	合計収益を`total_value`だけ減らし、合計返金額を増やします。
`ecommerce.cart_updated`	ユーザープロファイル上のカートマッピングオブジェクトを作成または更新します (カート全体のペイロード、または任意の`action` (`add`、`remove`、`replace`) による増分更新)。カートは30日間更新がないと期限切れになります。
`ecommerce.product_viewed`	ユーザープロファイルは変更されません。セグメンテーション、トリガー、BrazeAI^TM機能 (アイテムレコメンデーションなど) で利用できます。
`ecommerce.checkout_started`	ユーザープロファイルは変更されません。セグメンテーションとトリガー (チェックアウト放棄フローなど) で利用できます。

重要

USD以外の通貨の値は、イベントが報告された日の為替レートを使用して自動的にUSDに換算されます。すでにUSDで報告している場合は、意図しない換算を避けるため、通貨としてUSDをハードコードしてください。

実装の詳細

データポイントと請求

eコマースイベントはデータポイントを消費しません。データポイント使用量に影響を与えることなくログに記録できます。

イベントサイズの上限

/users/track に送信されるイベントプロパティは、1イベントあたり102,400バイト（100 KB）が上限です。トリガーされるキャンペーンおよびキャンバスのメッセージでは、/campaigns/trigger/send と /canvas/trigger/send に送信される trigger_properties に、より厳しいデフォルト上限である51,200バイト（50 KB）が適用されます。

ベストプラクティスとして、イベントのトリガー、パーソナライゼーション、アトリビューションに必要な製品情報のみを送信してください。説明、バリアントの完全なリスト、在庫、代替画像などの詳細な製品情報は、Brazeのカタログに保存します。メッセージを送信する際には、product_id または variant_id でこれらの詳細を参照します。metadata オブジェクトは、メッセージングで使用する注文または製品固有のコンテキストに限定して使用してください。

通貨の処理

Brazeは、USD以外の通貨の値を、イベントが報告された日の為替レートを使用して自動的にUSDに換算します。収益指標には、この換算後の値が表示されます。

ヒント

USDのみで事業を行っている場合は、不要な換算を避けるため、すべてのイベントで "currency": "USD" をハードコーディングしてください。

ソースフィールド

source プロパティは、イベントの発生元を識別する必須の文字列です。たとえば、shopify、in-store POS、custom_api などです。これにより、Currentsのエクスポートでデータを分析したり、バリデーションの問題をデバッグしたりする際に、連携ソースを区別しやすくなります。

メタデータの柔軟性

イベントレベルと製品レベルのメタデータオブジェクトはどちらも任意のキーと値のペアを受け付けるため、コアスキーマを変更せずにカスタムディメンションを付加できます。一般的な例としては、order_status_url、gift_wrapped、loyalty_points_earned、warehouse_id などがあります。これらのプロパティは、Liquidのパーソナライゼーション、Currentsのエクスポート、そしてセグメントエクステンションによるセグメンテーションで利用できます。

重要

推奨イベントは厳格なスキーマを使用します。そのため、properties のトップレベルにカスタムプロパティを追加すると、バリデーションに失敗します。すべてのカスタムプロパティは、イベントレベルの metadata オブジェクト、または products[] 内の製品レベルの metadata オブジェクトに入れてください。これらはトップレベルのフィールドと同様に、Liquid、Currents、セグメンテーションで引き続き利用できます。

イベントのバリデーションとトラブルシューティング

/users/track または任意のBraze SDKから推奨eコマースイベントを送信すると、Brazeは推奨イベントの処理中に、ペイロードをそのイベントのJSONスキーマに照らしてバリデーションします。バリデーションは、名前が推奨イベント（ecommerce.order_placed や ecommerce.cart_updated など）と完全に一致するすべてのイベントに対して自動的に実行されます。

バリデーションの内容

名前がeコマース推奨イベントと一致する各イベントについて、Brazeは次の項目をチェックします。

チェック項目	例
イベント名	完全に一致する必要があります。たとえば、`ecommerce.cart_updated` は正しく、`ecommerce.Cart_Updated`、`cartupdated`、`cart_updated` は正しくありません。
必須プロパティの有無	`order_placed` には `order_id`、`total_value`、`currency`、`products`、`source` が必要です。
正しいデータタイプ	`total_value` は数値、`currency` は文字列、`products` は配列である必要があります。
余分なトップレベルプロパティがないこと	properties の下にカスタムフィールドがあると失敗します。代わりに `metadata` オブジェクトを使用してください。
値の制約	金額フィールドは `0` 以上である必要があります。`currency` は有効なISO 4217文字列である必要があります。
製品ごとのフィールド	`products[]` の各アイテムには、`product_id`、`product_name`、`variant_id`、`quantity`、`price` が含まれている必要があります。

バリデーションを行う理由

eコマースイベントは、収益トラッキング、{% shopping_cart %} Liquidタグ、カート放棄トリガー、レポートなど、一貫性のある予測可能なデータに依存する機能を支えています。ペイロードがスキーマから外れると、これらの機能では気づかないうちに不正確な結果（誤った収益合計、カートの欠落、トリガーの不具合）が生じます。バリデーションによって事前に仕様を徹底することで、ダウンストリームの機能が予測どおりに動作するようになります。

バリデーションに成功した場合

イベントはeコマース推奨イベントとして処理され、関連するすべての後処理が実行されます。各イベントタイプによってトリガーされる動作の一覧については、eコマース推奨イベントを参照してください。

イベントの成功を確認する

イベントを送信した後、次のいずれかの方法で、イベントが受け付けられ正しく処理されたことを確認できます。

イベントユーザーログ：ダッシュボードでユーザーのプロファイルを開き、アクティビティを確認します。推奨イベントはプロパティのペイロード全体とともに表示されるため、イベントが記録されたことと、値が送信した内容と一致していることを確認できます。
カスタムイベントレポート：分析 > カスタムイベントレポートに移動すると、各推奨イベントの時系列の集計数を確認できます。統合が本番稼働しているときに、本番トラフィックが想定どおりに流れていることを確認するのに役立ちます。
テストユーザー：開発用ワークスペースのユーザーをテストユーザーとして指定し、そのユーザーに対して統合からイベントをトリガーします。テストユーザーはダッシュボードでフラグが付けられるため、エンドツーエンドの動作を簡単に切り分けて確認できます。

バリデーションに失敗した場合

イベントは推奨イベントとして処理されません。具体的には次のとおりです。

イベントは完全に破棄されます。 無効な推奨eコマースイベントはユーザープロファイルに記録されず、Currentsにも表示されず、セグメンテーションにも使用できません。
次のようなダウンストリームの推奨イベント機能は実行されません。
- 収益トラッキング（収益レポート、total_revenue などのユーザー計算フィールド）
- ユーザープロファイル上のカートオブジェクトの更新
- キャンバスとキャンペーンにおけるカートの更新または注文の確定トリガー

エラーの報告方法は、取り込み経路によって異なります。

REST API（/users/track）： 無効なイベントはそれぞれ、レスポンスの errors 配列で報告されます。各エントリには、どのイベントが失敗したか（index）と、その理由（type）が示されます。トップレベルの message フィールドは「success」のままですが、これはリクエストがBrazeに到達したことを意味するだけで、すべてのイベントが有効だったことを意味するものではありません。必ずレスポンス内の errors 配列を確認してください。
Braze SDK： SDKの呼び出しはすぐに返り、バリデーションはバックグラウンドで実行されるため、エラーはアプリに返されません。eコマースイベントのバリデーション失敗を把握するには、失敗サマリーメールを確認してください（失敗の確認を参照）。

APIエラーレスポンスの例

/users/track エンドポイントは、どのプロパティが失敗したか、およびその理由を示すフィールドレベルのエラーを返します。イベントはパイプラインに受け付けられているため、トップレベルの message は "success" を返す場合があることに注意してください。どのフィールドがスキーマのバリデーションに失敗したかは、errors 配列で確認できます。次のエラーレスポンスの例を参照してください。

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

失敗は内部的にも分類され、失敗サマリーメール用に集計されます。

失敗タイプ	意味	例
`missing_property`	必須フィールドがありません。	`order_placed` が `order_id` なしで送信された。
`extra_property`	スキーマで定義されていないフィールドが追加されています。	カスタムの `gift_wrapped` フィールドが `metadata` 内ではなく `properties` のトップレベルにある。
`unexpected_data_type`	フィールドのタイプが間違っています。	`29.99`（数値）ではなく `total_value: "29.99"`（文字列）になっている。

注

推奨イベントと完全に一致しないイベント名（ecommerce.OrderPlaced など）はバリデーションが完全にスキップされ、通常のカスタムイベントとして記録されます。これらは送信した名前でCurrentsやセグメンテーションに表示されますが、推奨イベントとしての処理は行われず、レスポンスに errors エントリも含まれません。

失敗の確認

Brazeは、推奨イベントのバリデーション失敗のサマリーをワークスペース管理者にメールで送信します。これにより、すべてのイベントを手動でモニタリングすることなく、統合の問題を特定して修正できます。

サマリーメールには次の内容が含まれます。

エラーの合計数： レポート期間中のエラー数。
イベント別のエラー： 推奨イベントタイプごと（ecommerce.cart_updated や ecommerce.order_placed など）に失敗したイベント数の内訳。統合内のどのイベントを優先的に対応すべきかを特定するのに使用します。
ソース別のエラー： APIとSDKの内訳。どの統合で失敗が発生しているかを特定できます。

これらのメールが届かない場合や、受信者リストを確認したい場合は、Brazeのアカウントチームにお問い合わせください。

失敗の診断と修正

失敗サマリーメールを受け取ったら、次の手順で対応します。

失敗しているイベントとソースを特定します。 メールでは、失敗がイベント名と統合ソース（sdk と rest_api）ごとに分けられているため、どの統合を修正する必要があるかを特定できます。同じイベントを複数のソースから送信している場合（たとえば、ストアフロントのSDKとバックエンドのWebhookの両方から cart_updated を送信している場合）は、それぞれ個別に対応してください。
ペイロードをイベントスキーマのスキーマと比較します。 ほとんどの失敗は、次の3つのパターンのいずれかに該当します。
- missing_property：必須フィールドがありません。解決するには、必須フィールドを追加します。
- extra_property：カスタムフィールドが properties のトップレベルにあります。解決するには、カスタムフィールドを metadata（イベントレベル）または products[].metadata（製品ごと）の中に移動します。
- unexpected_data_type：値のタイプが間違っています（たとえば、total_value が文字列として送信されている）。解決するには、送信前に値を変換します。
本番環境に展開する前に、修正したペイロードを開発用ワークスペースでテストします。 テストユーザーに対して既知のテストイベントを送信し、そのユーザーのプロファイルで想定どおりの推奨イベントの動作（カートオブジェクトの更新、収益の増加、カート放棄トリガーの発火など）を確認します。
次の失敗メールをモニタリングし、そのイベント、ソース、タイプの失敗数がゼロになったことを確認します。

イベントごとのプロパティ要件の詳細については、イベントスキーマを参照してください。

New Stuff!

推奨イベント

eコマース推奨イベント

eコマースイベントの仕組み

イベントの命名

イベントスキーマ

クライアント側の実装

イベントプロパティ

REST APIの例

クライアント側の実装

チェックアウトまたは注文後のカートID

イベントプロパティ

製品プロパティ (products[])

クライアント側の実装

イベントプロパティ

製品プロパティ (products[])

REST APIの例

クライアント側の実装

イベントプロパティ

製品プロパティ (products[])

REST APIの例

クライアント側の実装

イベントプロパティ

製品プロパティ (products[])

REST APIの例

クライアント側の実装

イベントプロパティ

製品プロパティ (products[])

REST APIの例

eコマースイベントの後処理

実装の詳細

データポイントと請求

イベントサイズの上限

通貨の処理

ソースフィールド

メタデータの柔軟性

イベントのバリデーションとトラブルシューティング

バリデーションの内容

バリデーションを行う理由

バリデーションに成功した場合

イベントの成功を確認する

バリデーションに失敗した場合

APIエラーレスポンスの例

失敗の確認

失敗の診断と修正

製品プロパティ (`products[]`)

製品プロパティ (`products[]`)

製品プロパティ (`products[]`)

製品プロパティ (`products[]`)

製品プロパティ (`products[]`)