이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

추천 이벤트

추천 이벤트는 정의된 JSON 스키마를 가진 표준화된 커스텀 이벤트를 전송하는 프레임워크를 기반으로 구축됩니다. 추천 이벤트를 전송하면 Braze는 수집 시 해당 스키마에 대해 유효성을 검사하고, 일반 커스텀 이벤트에서는 제공되지 않는 자동 필드 계산이나 장바구니 관리와 같은 특수 처리를 적용합니다. 특정 산업 이벤트 세트의 경우, Braze는 Campaigns 및 Canvases에 대한 전용 액션 기반 트리거와 같은 특별한 처리도 지원합니다.

eCommerce 추천 이벤트

eCommerce 추천 이벤트는 구매 여정의 여섯 단계를 다룹니다: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled, order_refunded. 이러한 이벤트를 성공적으로 전송하면, Braze가 데이터를 검증하고 점점 늘어나는 플랫폼 기능에서 사용할 수 있도록 합니다.

이러한 기능에는 유기한 브라우징, 유기한 장바구니, 유기한 결제, 주문 확인 흐름을 위한 Canvas 템플릿, eCommerce 리포팅, 그리고 총 매출, 총 주문 수, 총 환불액에 대한 계산된 고객 프로필 필드가 포함됩니다. 또한 세그먼트 확장을 통해 중첩된 제품 속성정보 필터링으로 Segments를 구축하고, {% shopping_cart %} Liquid 태그를 사용하여 유기한 장바구니 메시지를 개인화하며, 예측 이벤트, 예측 이탈, 아이템 추천 등의 BrazeAI^TM 기능을 활용할 수 있습니다.

이러한 이벤트는 정의된 스키마를 따르기 때문에, 지원되는 각 기능은 사용자 측에서 커스텀 속성정보 매핑이나 기능별 구성 없이도 구조화된 데이터를 읽을 수 있습니다.

중요

레거시 구매 이벤트는 유지보수 모드로 전환됩니다. 기존 Braze 고객은 레거시 구매 이벤트를 계속 사용할 수 있습니다. 기존 구매 이벤트는 계속 정상적으로 작동하지만, 향후 새로운 기능은 이커머스 추천 이벤트를 기반으로 구축됩니다. Braze는 서비스 종료일이 설정되기 전에 충분한 사전 공지를 제공합니다. 신규 Braze 고객은 레거시 구매 이벤트를 사용할 수 없으므로 이커머스 추천 이벤트를 사용해야 합니다.

eCommerce 이벤트 작동 방식

eCommerce 이벤트는 사전 정의된 이름과 속성정보 스키마를 가진 커스텀 이벤트입니다. Braze SDK, /users/track REST API 엔드포인트 또는 클라우드 데이터 수집(CDI)을 사용하여 전송하면, Braze가 수집 시 각 이벤트를 해당 스키마에 대해 검증합니다. 검증이 통과하면, Braze는 매출 필드 계산 및 고객 프로필의 장바구니 상태 관리 등 해당 이벤트 유형에 특화된 후처리를 자동으로 적용합니다.

참고

CSV 업로드는 eCommerce 이벤트를 지원하지 않습니다. SDK, /users/track 또는 CDI를 사용하여 이러한 이벤트를 전송하세요.

eCommerce 이벤트는 다른 커스텀 이벤트가 작동하는 모든 곳에서 동일하게 작동합니다: 수행된 커스텀 이벤트에 대한 트리거 및 필터, 커스텀 이벤트 리포팅 등. 그러나 스키마 검증을 통해 다음과 같은 추가 기능이 활성화됩니다:

Campaigns, Canvases, 작업 경로 단계, 인앱 메시지 트리거, 콘텐츠 카드 제거에서의 “주문 완료” 트리거 동작
계산된 eCommerce 고객 프로필 필드(총 매출, 총 주문 수, 총 환불액)
유기한 장바구니 흐름을 위한 장바구니 상태 관리
예측 이벤트, 예측 이탈, 아이템 추천 등 BrazeAI^TM 기능을 위한 풍부한 데이터

플랫폼이 커스텀 이벤트를 지원하는 모든 곳에서 eCommerce 이벤트를 이름으로 참조할 수도 있습니다. 예를 들어, ecommerce.product_viewed 이벤트로 액션 기반 Campaign을 트리거하거나, ecommerce.checkout_started 이벤트를 필터링하여 Segment를 구축하거나, Currents를 통해 ecommerce.order_placed 이벤트를 내보낼 수 있습니다.

이벤트 이름 지정

이벤트 이름은 정확하고, 대소문자를 구분하며, 점으로 구분됩니다. 항상 표준 형식을 사용하세요. 이벤트 이름이 여섯 가지 표준 이름 중 하나와 정확히 일치하지 않으면, Braze는 이를 일반 커스텀 이벤트로 처리하며 eCommerce 후처리가 수행되지 않습니다.

이벤트를 커스터마이즈하거나 이름을 변경할 수 없습니다.

올바름: ecommerce.order_placed
올바르지 않음: order.placed, eCommerce_order_placed, Order_Placed

이벤트 스키마

여섯 가지 eCommerce 추천 이벤트는 구매 여정의 단계에 매핑됩니다. 사용자가 해당 동작을 완료하는 순간에 각 이벤트를 발행하세요.

여섯 가지 eCommerce 추천 이벤트(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 eCommerce 이벤트 API를 사용하며, ecommerce.order_cancelled와 ecommerce.order_refunded는 logCustomEvent를 사용합니다. 플랫폼별 구현 예시는 Braze SDK를 통한 eCommerce 이벤트 로깅을 참조하세요.

사용자가 제품 상세 페이지를 볼 때 트리거합니다. 이 이벤트는 Braze 카탈로그 재입고 알림 및 가격 인하 알림과 호환됩니다.

클라이언트 측 구현

사용 가능한 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통한 eCommerce 이벤트 로깅을 참조하세요.

이벤트 속성정보

속성정보 이름	데이터 유형	필수	설명
`product_id`	문자열	예	고유 제품 식별자(예: SKU 또는 아이템 ID).
`product_name`	문자열	예	제품 표시 이름.
`variant_id`	문자열	예	제품 배리언트 식별자(예: `shirt_medium_blue`).
`image_url`	문자열	아니요	제품 이미지 URL.
`product_url`	문자열	아니요	제품 페이지 URL.
`price`	플로트	예	조회 시점의 배리언트 단가.
`currency`	문자열	예	세 자리 ISO 4217 코드(예: `USD` 또는 `EUR`).
`source`	문자열	예	이벤트가 발생한 소스(예: `web`, `ios` 또는 `android`).
`type`	문자열 배열	아니요	Braze의 재입고 및 가격 인하 알림 카탈로그 트리거 기능을 사용하려면 필수입니다. 허용되는 값: `"price_drop"`, `"back_in_stock"`
`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"],
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

사용자의 장바구니 내용이 변경될 때마다 트리거합니다.

클라이언트 측 구현

사용 가능한 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통한 eCommerce 이벤트 로깅을 참조하세요.

이 이벤트는 두 가지 방법으로 전송할 수 있습니다:

전체 장바구니 교체: action을 생략하거나 action을 replace로 설정합니다. products에 절대 수량(장바구니 내 배리언트별 총 단위 수)을 포함한 전체 라인 아이템 세트를 포함합니다. total_value는 필수입니다.
증분 장바구니 업데이트: action을 add 또는 remove로 설정합니다. 변경된 라인 아이템만 포함합니다. 각 quantity는 장바구니의 총 수량이 아닌 추가하거나 제거할 단위 수입니다. add의 경우, Braze가 라인 수량을 증가시키거나 새 라인을 추가합니다. remove의 경우, Braze가 라인 수량을 감소시키고 수량이 0에 도달하면 라인을 제거합니다. total_value는 add와 remove에서 선택사항입니다.

경고

주어진 장바구니에 대해 증분 장바구니 업데이트(add 또는 remove) 또는 전체 교체(action 없음 또는 replace) 중 하나만 사용하세요. 동일한 cart_id에 대해 두 방식을 혼합하는 것은 권장되지 않으며 Braze에서 장바구니 상태가 일관성 없게 될 수 있습니다.

이 이벤트로 메시징을 트리거하려면, Canvas와 Campaigns에서 장바구니 업데이트 이벤트 수행 트리거를 사용하세요. 이 트리거에는 장바구니가 쇼핑 퍼널을 진행하지 못하게 하는 특별한 처리가 포함되어 있습니다.

팁

장바구니는 고객 프로필에 {% shopping_cart %} Liquid 태그를 구동하는 장바구니 매핑 오브젝트를 생성합니다. 장바구니는 업데이트 없이 30일이 지나면 만료됩니다. 두 고객 프로필이 병합되면 Braze는 두 장바구니 모두 보존합니다.

이벤트 속성정보

속성정보	데이터 유형	필수	설명
`cart_id`	문자열	예	장바구니의 고유 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트에서 공유됩니다.
`action`	문자열	아니요	`add`(수량 증가 또는 새 라인 추가), `remove`(수량 감소, `0`에서 라인 제거), `replace`(`action` 생략과 동일한 전체 장바구니 교체).
`total_value`	플로트	조건부	`action`이 생략되거나 `replace`일 때 필수. `action`이 `add` 또는 `remove`일 때 선택사항.
`subtotal_value`	플로트	아니요	장바구니 소계(할인 적용 후, 세금/배송 전).
`tax`	플로트	아니요	장바구니에 적용된 총 세금.
`shipping`	플로트	아니요	장바구니의 총 배송비.
`currency`	문자열	예	세 자리 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`).

사용자가 결제 플로우를 시작할 때(예: “결제하기”를 선택하거나 결제 페이지에 도달할 때) 트리거합니다.

클라이언트 측 구현

사용 가능한 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통한 eCommerce 이벤트 로깅을 참조하세요.

이벤트 속성정보

속성정보	유형	필수	설명
checkout_id	문자열	예	결제 세션의 고유 식별자.
cart_id	문자열	아니요	장바구니 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트에서 공유됩니다.
total_value	플로트	예	결제의 총 금액.
subtotal_value	플로트	아니요	소계(할인 적용 후, 세금/배송 전).
tax	플로트	아니요	결제에 적용된 총 세금.
shipping	플로트	아니요	총 배송비.
currency	문자열	예	세 자리 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"
        }
      }
    }
  ]
}

주문이 성공적으로 완료되거나 결제가 확인될 때 트리거합니다.

클라이언트 측 구현

사용 가능한 SDK eCommerce 이벤트 API를 사용하세요. 플랫폼별 구현 예시는 Braze SDK를 통한 eCommerce 이벤트 로깅을 참조하세요.

중요

이 이벤트는 주요 매출 드라이버입니다. 고객 프로필에서 total_revenue를 total_value 값만큼 증가시키고 total_orders를 1만큼 증가시킵니다.

이벤트 속성정보

속성정보	데이터 유형	필수	설명
`order_id`	문자열	예	주문의 고유 식별자.
`cart_id`	문자열	아니요	장바구니 식별자. 사용자의 장바구니 매핑을 위해 장바구니, 결제, 주문 이벤트에서 공유됩니다.
`total_value`	플로트	예	주문의 총 금액.
`subtotal_value`	플로트	아니요	소계(할인 적용 후, 세금/배송 전).
`tax`	플로트	아니요	주문에 적용된 총 세금.
`shipping`	플로트	아니요	총 배송비.
`currency`	문자열	예	세 자리 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를 통한 eCommerce 이벤트 로깅을 참조하세요.

중요

이 이벤트는 고객 프로필에서 total_orders를 1만큼 감소시킵니다. total_revenue에는 영향을 미치지 않습니다. 매출을 조정하려면 order_refunded를 사용하세요.

이벤트 속성정보

속성정보	유형	필수	설명
`order_id`	문자열	예	주문의 고유 식별자.
`total_value`	플로트	예	취소되는 주문의 총 금액. 0 이상이어야 합니다. 절대값을 전송하면 Braze가 감소를 처리합니다.
`subtotal_value`	플로트	아니요	소계(할인 적용 후, 세금/배송 전).
`tax`	플로트	아니요	주문에 적용된 총 세금.
`shipping`	플로트	아니요	총 배송비.
`currency`	문자열	예	세 자리 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를 통한 eCommerce 이벤트 로깅을 참조하세요.

중요

이 이벤트는 고객 프로필에서 total_revenue를 total_value 값만큼 감소시키고 total_refunds를 증가시킵니다. 부분 환불의 경우, total_value를 원래 주문 합계가 아닌 환불 금액으로만 설정하세요.

이벤트 속성정보

속성정보	데이터 유형	필수	설명
`order_id`	문자열	예	원래 주문의 고유 식별자.
`total_value`	플로트	예	환불의 총 금액. 0 이상이어야 합니다. 절대값을 전송하면 Braze가 total_refunds 증가를 처리합니다.
`currency`	문자열	예	세 자리 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"
        }
      }
    }
  ]
}

eCommerce 이벤트 후처리

eCommerce 이벤트를 전송하면, 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로 하드코딩하세요.

구현 세부 사항

데이터 포인트 및 과금

eCommerce 이벤트는 데이터 포인트를 소비하지 않습니다. 데이터 포인트 사용량에 영향을 주지 않고 이벤트를 기록할 수 있습니다.

이벤트 크기 제한

/users/track로 전송되는 이벤트 속성정보는 이벤트당 102,400바이트(100KB)로 제한됩니다. 트리거된 Campaign 및 Canvas 메시지의 경우, /campaigns/trigger/send 및 /canvas/trigger/send로 전송되는 trigger_properties는 기본 제한이 51,200바이트(50KB)로 더 엄격합니다.

모범 사례로, 이벤트를 트리거하거나 개인화하거나 어트리뷰션하는 데 필요한 제품 정보만 전송하세요. 설명, 전체 배리언트 목록, 재고, 대체 이미지 등 더 풍부한 제품 상세 정보는 Braze 카탈로그에 저장하세요. 메시지를 전송할 때 product_id 또는 variant_id로 이러한 상세 정보를 참조하세요. metadata 객체는 메시징에서 사용할 주문 또는 제품별 컨텍스트에 선택적으로 사용하세요.

통화 처리

Braze는 이벤트가 보고된 날짜의 환율을 사용하여 USD가 아닌 통화 값을 자동으로 USD로 변환합니다. 이 변환된 값이 매출 측정기준에 표시됩니다.

팁

USD만 사용하는 경우, 불필요한 변환을 방지하기 위해 모든 이벤트에 "currency": "USD"를 하드코딩하세요.

Source 필드

source 속성정보는 이벤트가 발생한 곳을 식별하는 필수 문자열입니다. 예를 들어, shopify, in-store POS, 또는 custom_api 등이 있습니다. 이를 통해 Currents 내보내기에서 데이터를 분석하거나 유효성 검사 문제를 디버깅할 때 통합 소스를 구분할 수 있습니다.

메타데이터 유연성

이벤트 수준 및 제품 수준 metadata 객체는 모두 임의의 키-값 페어를 허용하므로, 핵심 스키마를 수정하지 않고도 커스텀 차원을 첨부할 수 있습니다. 일반적인 예로는 order_status_url, gift_wrapped, loyalty_points_earned, 또는 warehouse_id 등이 있습니다. 이러한 속성정보는 Liquid 개인화, Currents 내보내기, 그리고 세그먼트 확장을 통한 세분화에서 사용할 수 있습니다.

중요

추천 이벤트는 엄격한 스키마를 사용합니다. 따라서 properties의 최상위 수준에 커스텀 속성정보를 추가하면 유효성 검사에 실패합니다. 모든 커스텀 속성정보는 이벤트 수준 metadata 객체 또는 products[] 내부의 제품 수준 metadata 객체에 넣으세요. 이렇게 해도 최상위 수준 필드와 마찬가지로 Liquid, Currents, 세분화에서 사용할 수 있습니다.

이벤트 유효성 검사 및 문제 해결

추천 이커머스 이벤트를 /users/track 또는 Braze SDK를 통해 전송하면, Braze는 추천 이벤트 처리 과정에서 페이로드를 이벤트의 JSON 스키마에 따라 유효성 검사합니다. 유효성 검사는 추천 이벤트와 이름이 정확히 일치하는 모든 이벤트(예: ecommerce.order_placed 또는 ecommerce.cart_updated)에 대해 자동으로 실행됩니다.

검사 항목

이커머스 추천 이벤트와 이름이 일치하는 각 이벤트에 대해 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`가 포함되어야 합니다.

유효성 검사 이유

이커머스 이벤트는 매출 추적, {% shopping_cart %} Liquid 태그, 유기한 장바구니 트리거, 보고서 등 일관되고 예측 가능한 데이터에 의존하는 기능을 구동합니다. 페이로드가 스키마와 다를 경우, 이러한 기능은 잘못된 매출 합계, 누락된 장바구니, 손상된 트리거 등 감지되지 않는 부정확한 결과를 초래합니다. 유효성 검사는 다운스트림 기능이 예측 가능하게 동작하도록 사전에 계약을 적용합니다.

유효성 검사 통과 시

이벤트는 모든 관련 후처리와 함께 이커머스 추천 이벤트로 처리됩니다. 각 이벤트 유형에 의해 트리거되는 전체 동작 목록은 이커머스 추천 이벤트를 참조하세요.

성공적인 이벤트 확인

이벤트를 전송한 후 다음 방법 중 하나를 사용하여 이벤트가 수락되고 올바르게 처리되었는지 확인할 수 있습니다.

이벤트 사용자 로그: 대시보드에서 사용자의 프로필을 열고 활동을 확인하세요. 추천 이벤트는 전체 속성정보 페이로드와 함께 표시되므로, 이벤트가 도착했는지와 값이 전송한 내용과 일치하는지 확인할 수 있습니다.
커스텀 이벤트 리포트: Analytics > Custom Events Report로 이동하여 시간에 따른 각 추천 이벤트의 집계 수를 확인하세요. 통합이 라이브 상태일 때 프로덕션 트래픽이 예상대로 흐르고 있는지 확인하는 데 유용합니다.
테스트 사용자: 개발 워크스페이스에서 사용자를 테스트 사용자로 표시한 다음, 해당 사용자를 대상으로 통합에서 이벤트를 트리거하세요. 테스트 사용자는 대시보드에서 플래그가 지정되어, 포괄적인 동작을 쉽게 분리하고 검사할 수 있습니다.

유효성 검사 실패 시

이벤트는 추천 이벤트로 처리되지 않습니다. 구체적으로 다음과 같습니다.

이벤트가 완전히 삭제됩니다. 유효하지 않은 추천 이커머스 이벤트는 고객 프로필에 기록되지 않고, Currents에 나타나지 않으며, 세분화에 사용할 수 없습니다.
다음을 포함한 다운스트림 추천 이벤트 기능이 실행되지 않습니다.
- 매출 추적(매출 보고, total_revenue 등 사용자 계산 필드)
- 고객 프로필의 장바구니 객체 업데이트
- Canvas 및 Campaigns의 Update Cart 또는 Place Order 트리거

오류 보고 방식은 수집 경로에 따라 다릅니다.

REST API(/users/track): 유효하지 않은 각 이벤트는 응답의 errors 배열에 보고됩니다. 각 항목은 어떤 이벤트가 실패했는지(인덱스)와 이유(유형)를 알려줍니다. 최상위 message 필드는 여전히 “success”로 표시되지만, 이는 요청이 Braze에 도달했다는 의미일 뿐 모든 이벤트가 유효하다는 의미가 아닙니다. 항상 응답에서 errors 배열을 확인하세요.
Braze SDK: SDK 호출은 즉시 반환되고 유효성 검사는 백그라운드에서 실행되므로, 오류가 앱으로 다시 전송되지 않습니다. 이커머스 이벤트 유효성 검사 실패를 확인하려면 실패 요약 이메일을 확인하세요(실패 확인 참조).

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`	스키마에 정의되지 않은 필드가 추가되었습니다.	`metadata` 내부가 아닌 `properties` 최상위에 커스텀 `gift_wrapped` 필드를 추가한 경우.
`unexpected_data_type`	필드의 유형이 잘못되었습니다.	`total_value: "29.99"` (문자열) 대신 `29.99` (숫자)여야 합니다.

참고

추천 이벤트와 정확히 일치하지 않는 이벤트 이름(예: ecommerce.OrderPlaced)은 유효성 검사를 완전히 건너뛰고 일반 커스텀 이벤트로 기록됩니다. 이러한 이벤트는 전송한 이름으로 Currents와 세분화에 표시되지만, 추천 이벤트 처리는 수행되지 않으며 응답에 errors 항목도 포함되지 않습니다.

실패 확인

Braze는 워크스페이스 관리자에게 추천 이벤트 유효성 검사 실패 요약을 이메일로 전송하므로, 모든 이벤트를 수동으로 모니터링하지 않고도 통합 문제를 식별하고 수정할 수 있습니다.

요약 이메일에는 다음이 포함됩니다.

총 오류 수: 보고 기간의 오류 수입니다.
이벤트별 오류: 각 추천 이벤트 유형(예: ecommerce.cart_updated, ecommerce.order_placed)에 대해 실패한 이벤트 수의 분석입니다. 통합에서 어떤 이벤트를 우선적으로 수정해야 하는지 파악하는 데 사용하세요.
소스별 오류: API와 SDK 간의 분류로, 어떤 통합이 실패를 발생시키고 있는지 정확히 파악할 수 있습니다.

이러한 이메일을 받지 못하거나 수신자 목록을 확인하려면 Braze 계정 팀에 문의하세요.

실패 진단 및 수정

실패 요약 이메일을 받으면 다음을 수행하세요.

실패한 이벤트와 소스를 식별합니다. 이메일은 이벤트 이름과 통합 소스(sdk 대 rest_api)별로 실패를 구분하므로, 어떤 통합을 수정해야 하는지 정확히 파악할 수 있습니다. 동일한 이벤트를 전송하는 여러 소스가 있는 경우(예: 스토어프론트 SDK와 백엔드 웹훅 모두 cart_updated를 전송하는 경우) 각각 별도로 처리하세요.
이벤트 스키마에서 페이로드를 스키마와 비교합니다. 대부분의 실패는 다음 세 가지 패턴 중 하나에 해당합니다.
- missing_property: 필수 필드가 누락되었습니다. 이를 해결하려면 필수 필드를 추가하세요.
- extra_property: 커스텀 필드가 properties의 최상위에 있습니다. 이를 해결하려면 커스텀 필드를 metadata(이벤트 수준) 또는 products[].metadata(제품별) 내부로 이동하세요.
- unexpected_data_type: 값의 유형이 잘못되었습니다(예: total_value가 문자열로 전송된 경우). 이를 해결하려면 전송 전에 값을 변환하세요.
수정된 페이로드를 프로덕션에 배포하기 전에 개발 워크스페이스에서 테스트합니다. 테스트 사용자에 대해 알려진 테스트 이벤트를 전송한 다음, 해당 사용자의 프로필에서 예상되는 추천 이벤트 동작(예: 장바구니 객체 업데이트, 매출 증가, 유기한 장바구니 트리거 실행)을 확인하세요.
다음 실패 이메일을 모니터링하여 해당 이벤트, 소스, 유형의 실패 수가 0으로 감소했는지 확인합니다.

이벤트별 전체 속성정보 요구 사항은 이벤트 스키마를 참조하세요.

New Stuff!

추천 이벤트

eCommerce 추천 이벤트

eCommerce 이벤트 작동 방식

이벤트 이름 지정

이벤트 스키마

클라이언트 측 구현

이벤트 속성정보

REST API 예시

클라이언트 측 구현

이벤트 속성정보

제품 속성정보 (products[])

클라이언트 측 구현

이벤트 속성정보

제품 속성정보 (products[])

REST API 예시

클라이언트 측 구현

이벤트 속성정보

제품 속성정보 (products[])

REST API 예시

클라이언트 측 구현

이벤트 속성정보

제품 속성정보 (products[])

REST API 예시

클라이언트 측 구현

이벤트 속성정보

제품 속성정보 (products[])

REST API 예시

eCommerce 이벤트 후처리

구현 세부 사항

데이터 포인트 및 과금

이벤트 크기 제한

통화 처리

Source 필드

메타데이터 유연성

이벤트 유효성 검사 및 문제 해결

검사 항목

유효성 검사 이유

유효성 검사 통과 시

성공적인 이벤트 확인

유효성 검사 실패 시

API 오류 응답 예시

실패 확인

실패 진단 및 수정

제품 속성정보 (`products[]`)

제품 속성정보 (`products[]`)

제품 속성정보 (`products[]`)

제품 속성정보 (`products[]`)

제품 속성정보 (`products[]`)