이 페이지는 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는 수집 시 각 이벤트를 해당 스키마에 대해 검증합니다. 유효성 검사를 통과하면 이벤트 유형별 후처리를 자동으로 적용합니다. 예를 들어 매출 필드를 계산하고 고객 프로필의 장바구니 상태를 관리합니다.

eCommerce 이벤트는 다른 커스텀 이벤트를 사용할 수 있는 모든 곳에서 작동합니다. 수행한 커스텀 이벤트에 대한 트리거와 필터, 커스텀 이벤트 보고 등이 여기에 포함됩니다. 또한 스키마 유효성 검사 덕분에 다음과 같은 추가 기능을 사용할 수 있습니다.

Campaign, Canvas, 작업 경로 단계, 인앱 메시지 트리거, 콘텐츠 카드 제거에서 사용하는 “주문하기” 트리거 동작
계산된 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 REST API를 통해 서버에서 전송합니다. 이러한 이벤트는 환불 흐름처럼 서버 측 로직이 완료되어야 하는 경우가 많기 때문입니다. 플랫폼별 구현 예시는 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을 생략하거나 replace로 설정합니다. products에 전체 라인 항목을 절대 수량(장바구니에 있는 배리언트별 총 개수)과 함께 포함합니다. total_value를 반드시 포함해야 합니다.
증분 장바구니 업데이트: action을 add 또는 remove로 설정하고, 변경된 라인 항목만 포함합니다. 각 quantity는 장바구니의 총 수량이 아니라 추가하거나 제거할 개수입니다.
- add: Braze가 라인 수량을 늘리거나 새 라인을 추가합니다.
- remove: Braze가 라인 수량을 줄이고, 수량이 0이 되면 해당 라인을 제거합니다.
- add와 remove에서는 total_value가 선택 사항입니다.

경고

하나의 장바구니에는 증분 장바구니 업데이트(add 또는 remove)와 전체 교체(action 없음 또는 replace) 중 한 가지 방식만 사용하세요. 같은 cart_id에 두 방식을 혼용하면 Braze의 장바구니 상태가 일관되지 않을 수 있으므로 권장하지 않습니다.

이 이벤트로 메시징을 트리거하려면 Canvas와 Campaign에서 Perform Cart Updated Event 트리거를 사용하세요. 이 트리거에는 장바구니가 쇼핑 퍼널을 계속 진행하지 않도록 하는 특별 처리가 포함되어 있습니다.

팁

장바구니는 고객 프로필에 장바구니 매핑 객체를 생성합니다. 이 객체는 {% 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"를 하드코딩하세요.

소스 필드

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

메타데이터 유연성

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

중요

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

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

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

검증 항목

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

유효성 검사를 하는 이유

eCommerce 이벤트는 매출 추적, {% shopping_cart %} Liquid 태그, 유기한 장바구니 트리거, 보고 등 일관되고 예측 가능한 데이터에 의존하는 기능을 구동합니다. 페이로드가 스키마와 다르면 이러한 기능에서 눈에 띄지 않는 오류(잘못된 매출 합계, 누락된 장바구니, 작동하지 않는 트리거)가 발생합니다. 유효성 검사는 사전에 규약을 적용하여 다운스트림 기능이 예측 가능하게 작동하도록 합니다.

유효성 검사를 통과한 경우

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

성공한 이벤트 확인

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

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

유효성 검사에 실패한 경우

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

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

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

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

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_id` 없이 `order_placed`를 보낸 경우.
`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와 백엔드 웹훅이 모두 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 이벤트 후처리

구현 세부 사항

데이터 포인트 및 청구

이벤트 크기 제한

통화 처리

소스 필드

메타데이터 유연성

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

검증 항목

유효성 검사를 하는 이유

유효성 검사를 통과한 경우

성공한 이벤트 확인

유효성 검사에 실패한 경우

API 오류 응답 예시

실패 찾기

실패 진단 및 수정

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

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

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

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

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