Skip to content

Eventos recomendados

Los eventos recomendados se basan en un marco que envía eventos personalizados estandarizados con esquemas JSON definidos. Cuando envías un evento recomendado, Braze lo valida contra su esquema en la ingesta y aplica un procesamiento especializado, como cálculos automáticos de campos o gestión del carrito, que los eventos personalizados genéricos no reciben. Para ciertos conjuntos de eventos de la industria, Braze también admite un tratamiento especial, como desencadenantes basados en acciones dedicados para Campaigns y Canvas.

Los eventos recomendados de comercio electrónico cubren seis pasos en el recorrido de compra: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded. Cuando envías estos eventos correctamente, Braze valida los datos y los pone a disposición de un conjunto creciente de características de la plataforma.

Estas características incluyen plantillas de Canvas para flujos de navegación abandonada, carrito abandonado, pago abandonado y confirmación de pedido; informes de comercio electrónico; y campos calculados del perfil de usuario para Total Revenue, Total Orders y Total Refunds. También puedes crear segmentos usando filtrado de propiedades de producto anidadas a través de Extensiones de segmento, personalizar mensajes de carrito abandonado con la etiqueta de Liquid {% shopping_cart %}, y alimentar las capacidades de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos, junto con otras capacidades.

Dado que estos eventos siguen un esquema definido, cada característica compatible puede leer los datos estructurados sin necesidad de mapeado personalizado de propiedades ni configuración por característica de tu parte.

Cómo funcionan los eventos de comercio electrónico

Los eventos de comercio electrónico son eventos personalizados con nombres y esquemas de propiedades predefinidos. Los envías usando el SDK de Braze o el punto de conexión REST API /users/track, y Braze valida cada evento contra su esquema en la ingesta. Cuando la validación es exitosa, Braze aplica automáticamente el posprocesamiento específico de ese tipo de evento, como calcular campos de ingresos y gestionar el estado del carrito en los perfiles de usuario.

Los eventos de comercio electrónico funcionan en todos los lugares donde funcionan otros eventos personalizados: desencadenantes y filtros para eventos personalizados realizados, informes de eventos personalizados y más. Sin embargo, su validación de esquema desbloquea capacidades adicionales, incluyendo:

  • Acciones desencadenantes “Realiza un pedido” en Campaigns, Canvas, rutas de acción, desencadenantes de mensajes dentro de la aplicación y eliminación de tarjetas de contenido
  • Campos calculados del perfil de usuario de comercio electrónico (Total Revenue, Total Orders, Total Refunds)
  • Gestión del estado del carrito para flujos de carrito abandonado
  • Datos más ricos para las características de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos

También puedes hacer referencia a los eventos de comercio electrónico por nombre en cualquier lugar donde la plataforma admita eventos personalizados. Por ejemplo, puedes desencadenar una Campaign basada en acciones con eventos ecommerce.product_viewed, crear un segmento filtrando por eventos ecommerce.checkout_started, o exportar eventos ecommerce.order_placed a través de Currents.

Nomenclatura de eventos

Los nombres de los eventos son exactos, distinguen entre mayúsculas y minúsculas, y están delimitados por puntos. Usa siempre el formato canónico. Si un nombre de evento no coincide exactamente con uno de los seis nombres canónicos, Braze lo trata como un evento personalizado estándar y no se realiza ningún posprocesamiento de comercio electrónico.

No puedes personalizar ni renombrar eventos.

  • Correcto: ecommerce.order_placed
  • Incorrecto: order.placed, eCommerce_order_placed, Order_Placed

Esquemas de eventos

Los seis eventos recomendados de comercio electrónico se corresponden con etapas del recorrido de compra. Dispara cada evento en el momento en que el usuario completa la acción correspondiente.

Diagrama del recorrido del usuario a través de los seis eventos recomendados de comercio electrónico: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded.

Se desencadena cuando un usuario ve una página de detalle de producto. Este evento es compatible con las notificaciones de vuelta en stock y las notificaciones de bajada de precio del catálogo de Braze.

Propiedades del evento

Nombre de la propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto (por ejemplo, SKU o ID de artículo).
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante del producto (por ejemplo, shirt_medium_blue).
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto para más detalles.
price Float Sí Precio unitario de la variante en el momento de la visualización.
currency String Sí Código ISO 4217 de tres letras (por ejemplo, USD o EUR).
source String Sí Fuente de la que se origina el evento (por ejemplo, web, ios o android).
type Array of strings No Obligatoria para usar las características de desencadenantes de catálogo de Braze para alertas de vuelta en stock y bajada de precio. Valores aceptados: "price_drop", "back_in_stock"
metadata Object No Pares clave-valor flexibles. Subpropiedad reconocida: sku (String)

Ejemplo de REST API

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "sku": "UB-BLK-11-SKU",
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Se desencadena cada vez que cambia el contenido del carrito de un usuario.

Puedes enviar este evento de dos maneras:

  • Reemplazo completo del carrito: Omite action o establece action en replace. Incluye el conjunto completo de artículos en products con cantidades absolutas (unidades totales por variante en el carrito). Debes incluir total_value.
  • Actualizaciones incrementales del carrito: Establece action en add o remove. Incluye solo los artículos que cambiaron. Cada quantity es el número de unidades a agregar o quitar, no la cantidad total en el carrito. Para add, Braze incrementa la cantidad de la línea o agrega una nueva línea. Para remove, Braze decrementa la cantidad de la línea y la elimina cuando la cantidad llega a 0. total_value es opcional para add y remove.

Para desencadenar mensajería a partir de este evento, usa el desencadenante Perform Cart Updated Event en Canvas y Campaigns. Este desencadenante incluye un tratamiento especial para evitar que el carrito avance a través del embudo de compras.

Propiedades del evento

Propiedad Tipo de datos Obligatoria Descripción
cart_id String Sí Identificador único del carrito. Compartido entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
action String No add (incrementar cantidad o agregar una línea), remove (decrementar cantidad; la línea se elimina en 0) o replace (reemplazo completo del carrito, igual que omitir action).
total_value Float Condicional Obligatoria cuando se omite action o es replace. Opcional cuando action es add o remove.
subtotal_value Float No Valor del subtotal del carrito (después de descuentos, antes de impuestos/envío).
tax Float No Impuesto total aplicado al carrito.
shipping Float No Costo total de envío del carrito.
currency String Sí Código ISO 4217 de tres letras.
products Array Sí Artículos para esta actualización. Para reemplazo completo (sin action o replace), incluye el carrito completo con cantidades absolutas. Para add o remove, incluye solo las líneas que cambiaron; consulta las propiedades de producto.
source String Sí Fuente de la que se origina el evento.
metadata Object No Pares clave-valor flexibles para datos adicionales a nivel de evento.

Propiedades de producto (products[])

Propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto.
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante.
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto.
quantity Integer Sí Para reemplazo completo (sin action o replace), unidades en el carrito para esta línea. Para add o remove, cuántas unidades agregar o quitar.
price Float Sí Precio unitario de la variante.
metadata Object No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplos de código

Cada pestaña de plataforma a continuación usa el diseño de fragmento de código que corresponde a esa ruta de integración (por ejemplo, encabezados o etiquetas dentro de un bloque delimitado). Las cargas útiles de add, remove y replace son las mismas en todas las plataformas; solo difiere la superficie del SDK o la API.

add

add incrementa la cantidad o agrega una nueva línea. La propiedad quantity indica cuántas unidades agregar.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "add",
  currency: "USD",
  source: "web",
  products: [
    {
      product_id: "SKU-RUN-4821",
      product_name: "Ultraboost Running Shoe",
      variant_id: "UB-BLK-11",
      quantity: 1,
      price: 189.99,
    },
  ],
});
remove

remove decrementa la cantidad en el monto indicado en quantity. La línea se elimina cuando la cantidad llega a 0.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "remove",
  currency: "USD",
  source: "web",
  products: [
    {
      product_id: "SKU-SOC-1102",
      product_name: "Performance Running Socks",
      variant_id: "SOC-WHT-L",
      quantity: 1,
      price: 14.99,
    },
  ],
});
replace

replace (u omitir action) envía el carrito completo. total_value es obligatoria.

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

braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "replace",
  total_value: 234.96,
  currency: "USD",
  source: "web",
  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,
    },
    {
      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,
    },
  ],
});
Añadir

add incrementa la cantidad o agrega una nueva línea. La propiedad quantity indica cuántas unidades agregar.

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

Kotlin

// add — units to add
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "add")
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray().put(
          JSONObject()
            .put("product_id", "SKU-RUN-4821")
            .put("product_name", "Ultraboost Running Shoe")
            .put("variant_id", "UB-BLK-11")
            .put("quantity", 1)
            .put("price", 189.99),
        ),
      ),
  ),
)

JavaScript

// add — units to add
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "add")
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99)))));
Eliminar

remove decrementa la cantidad en el monto indicado en quantity. La línea se elimina cuando la cantidad llega a 0.

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

Kotlin

// remove — units to remove
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "remove")
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray().put(
          JSONObject()
            .put("product_id", "SKU-SOC-1102")
            .put("product_name", "Performance Running Socks")
            .put("variant_id", "SOC-WHT-L")
            .put("quantity", 1)
            .put("price", 14.99),
        ),
      ),
  ),
)

JavaScript

// remove — units to remove
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "remove")
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-SOC-1102")
                .put("product_name", "Performance Running Socks")
                .put("variant_id", "SOC-WHT-L")
                .put("quantity", 1)
                .put("price", 14.99)))));
Reemplazar

replace (u omitir action) envía el carrito completo. total_value es obligatoria.

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

Kotlin

// replace — full cart; total_value required
Braze.getInstance(context).logCustomEvent(
  "ecommerce.cart_updated",
  BrazeProperties(
    JSONObject()
      .put("cart_id", "cart_abc123")
      .put("action", "replace")
      .put("total_value", 234.96)
      .put("currency", "USD")
      .put("source", "android")
      .put(
        "products",
        JSONArray()
          .put(
            JSONObject()
              .put("product_id", "SKU-RUN-4821")
              .put("product_name", "Ultraboost Running Shoe")
              .put("variant_id", "UB-BLK-11")
              .put("quantity", 1)
              .put("price", 189.99),
          )
          .put(
            JSONObject()
              .put("product_id", "SKU-SOC-1102")
              .put("product_name", "Performance Running Socks")
              .put("variant_id", "SOC-WHT-L")
              .put("quantity", 2)
              .put("price", 14.99),
          ),
      ),
  ),
)

JavaScript

// replace — full cart; total_value required
Braze.getInstance(context).logCustomEvent(
    "ecommerce.cart_updated",
    new BrazeProperties(new JSONObject()
        .put("cart_id", "cart_abc123")
        .put("action", "replace")
        .put("total_value", 234.96)
        .put("currency", "USD")
        .put("source", "android")
        .put("products", new JSONArray()
            .put(new JSONObject()
                .put("product_id", "SKU-RUN-4821")
                .put("product_name", "Ultraboost Running Shoe")
                .put("variant_id", "UB-BLK-11")
                .put("quantity", 1)
                .put("price", 189.99))
            .put(new JSONObject()
                .put("product_id", "SKU-SOC-1102")
                .put("product_name", "Performance Running Socks")
                .put("variant_id", "SOC-WHT-L")
                .put("quantity", 2)
                .put("price", 14.99)))));
Añadir

add incrementa la cantidad o agrega una nueva línea. La propiedad quantity indica cuántas unidades agregar.

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

Swift

// add — units to add
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "add",
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "quantity": 1,
        "price": 189.99,
      ],
    ],
  ]
)

Objective-C

// add — units to add
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"add",
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[@{
    @"product_id": @"SKU-RUN-4821",
    @"product_name": @"Ultraboost Running Shoe",
    @"variant_id": @"UB-BLK-11",
    @"quantity": @1,
    @"price": @189.99,
  }],
}];
Eliminar

remove decrementa la cantidad en el monto indicado en quantity. La línea se elimina cuando la cantidad llega a 0.

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

Swift

// remove — units to remove
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "remove",
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-SOC-1102",
        "product_name": "Performance Running Socks",
        "variant_id": "SOC-WHT-L",
        "quantity": 1,
        "price": 14.99,
      ],
    ],
  ]
)

Objective-C

// remove — units to remove
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"remove",
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[@{
    @"product_id": @"SKU-SOC-1102",
    @"product_name": @"Performance Running Socks",
    @"variant_id": @"SOC-WHT-L",
    @"quantity": @1,
    @"price": @14.99,
  }],
}];
Reemplazar

replace (u omitir action) envía el carrito completo. total_value es obligatoria.

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

Swift

// replace — full cart; total_value required
AppDelegate.braze?.logCustomEvent(
  name: "ecommerce.cart_updated",
  properties: [
    "cart_id": "cart_abc123",
    "action": "replace",
    "total_value": 234.96,
    "currency": "USD",
    "source": "ios",
    "products": [
      [
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "quantity": 1,
        "price": 189.99,
      ],
      [
        "product_id": "SKU-SOC-1102",
        "product_name": "Performance Running Socks",
        "variant_id": "SOC-WHT-L",
        "quantity": 2,
        "price": 14.99,
      ],
    ],
  ]
)

Objective-C

// replace — full cart; total_value required
[AppDelegate.braze logCustomEvent:@"ecommerce.cart_updated"
                       properties:@{
  @"cart_id": @"cart_abc123",
  @"action": @"replace",
  @"total_value": @234.96,
  @"currency": @"USD",
  @"source": @"ios",
  @"products": @[
    @{
      @"product_id": @"SKU-RUN-4821",
      @"product_name": @"Ultraboost Running Shoe",
      @"variant_id": @"UB-BLK-11",
      @"quantity": @1,
      @"price": @189.99,
    },
    @{
      @"product_id": @"SKU-SOC-1102",
      @"product_name": @"Performance Running Socks",
      @"variant_id": @"SOC-WHT-L",
      @"quantity": @2,
      @"price": @14.99,
    },
  ],
}];
add

add incrementa la cantidad o agrega una nueva línea. La propiedad quantity indica cuántas unidades agregar.

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:25:33Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "add",
        "currency": "USD",
        "source": "web",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99
          }
        ]
      }
    }
  ]
}
remove

remove decrementa la cantidad en el monto indicado en quantity. La línea se elimina cuando la cantidad llega a 0.

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:26:10Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "remove",
        "currency": "USD",
        "source": "web",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 1,
            "price": 14.99
          }
        ]
      }
    }
  ]
}
replace

replace (u omitir action) envía el carrito completo. total_value es obligatoria.

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.cart_updated",
      "time": "2026-04-28T14:27:00Z",
      "properties": {
        "cart_id": "cart_abc123",
        "action": "replace",
        "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": {
          "cart_source": "product_page_atc_button"
        }
      }
    }
  ]
}

Se desencadena cuando el usuario inicia el flujo de pago (por ejemplo, selecciona “Pagar” o llega a la página de pago).

Propiedades del evento

Propiedad Tipo Obligatoria Descripción
checkout_id String Sí Identificador único de la sesión de pago.
cart_id String No Identificador del carrito. Compartido entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
total_value Float Sí Valor monetario total del pago.
subtotal_value Float No Valor del subtotal (después de descuentos, antes de impuestos/envío).
tax Float No Impuesto total aplicado al pago.
shipping Float No Costo total de envío.
currency String Sí Código ISO 4217 de tres letras.
products Array Sí Artículos en proceso de pago. Consulta la subtabla de propiedades de producto.
source String Sí Fuente de la que se origina el evento.
metadata Object No Pares clave-valor flexibles. Subpropiedad reconocida: checkout_url (String)

Propiedades de producto (products[])

Propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto.
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante.
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto.
quantity Integer Sí Número de unidades en el carrito.
price Float Sí Precio unitario de la variante.
metadata Object No Pares clave-valor flexibles (por ejemplo, color, talla).

Ejemplo de REST API

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

Se desencadena cuando un pedido se completa correctamente o se confirma el pago.

Propiedades del evento

Propiedad Tipo de datos Obligatoria Descripción
order_id String Sí Identificador único del pedido.
cart_id String No Identificador del carrito. Compartido entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
total_value Float Sí Valor monetario total del pedido.
subtotal_value Float No Valor del subtotal (después de descuentos, antes de impuestos/envío).
tax Float No Impuesto total aplicado al pedido.
shipping Float No Costo total de envío.
currency String Sí Código ISO 4217 de tres letras.
total_discounts Float No Monto total de descuentos aplicados al pedido.
discounts Array No Lista detallada de descuentos aplicados.
products Array Sí Artículos en el pedido. Consulta la subtabla de propiedades de producto.
source String Sí Fuente de la que se origina el evento.
metadata Object No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (String)

Propiedades de producto (products[])

Propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto.
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante.
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto.
quantity Integer Sí Número de unidades en el carrito.
price Float Sí Precio unitario de la variante.
metadata Object No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplo de REST API

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se cancela un pedido.

Propiedades del evento

Propiedad Tipo Obligatoria Descripción
order_id String Sí Identificador único del pedido.
total_value Float Sí Valor monetario total del pedido que se cancela. Debe ser ≥ 0; envía el monto absoluto; Braze se encarga del decremento.
subtotal_value Float No Valor del subtotal (después de descuentos, antes de impuestos/envío).
tax Float No Impuesto total aplicado al pedido.
shipping Float No Costo total de envío.
currency String Sí Código ISO 4217 de tres letras.
total_discounts Float No Monto total de descuentos aplicados al pedido.
discounts Array No Lista detallada de descuentos aplicados.
cancel_reason String Sí Motivo por el que se canceló el pedido.
products Array Sí Artículos en el pedido cancelado. Consulta la subtabla de propiedades de producto.
source String Sí Fuente de la que se origina el evento.
metadata Object No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (String)

Propiedades de producto (products[])

Propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto.
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante.
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto.
quantity Integer Sí Número de unidades en el carrito.
price Float Sí Precio unitario de la variante.
metadata Object No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplo de REST API

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

{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se emite un reembolso total o parcial.

Propiedades del evento

Propiedad Tipo de datos Obligatoria Descripción
order_id String Sí Identificador único del pedido original.
total_value Float Sí Valor monetario total del reembolso. Debe ser ≥ 0; envía el monto absoluto; Braze se encarga del incremento a total_refunds.
currency String Sí Código ISO 4217 de tres letras.
total_discounts Float No Monto total de descuentos aplicados originalmente.
discounts Array No Lista detallada de descuentos.
products Array Sí Artículos que se reembolsan. Consulta la subtabla de propiedades de producto.
source String Sí Fuente de la que se origina el evento.
metadata Object No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (String).

Propiedades de producto (products[])

Propiedad Tipo de datos Obligatoria Descripción
product_id String Sí Identificador único del producto.
product_name String Sí Nombre de visualización del producto.
variant_id String Sí Identificador de la variante.
image_url String No URL de la imagen del producto.
product_url String No URL de la página del producto.
quantity Integer Sí Número de unidades en el carrito.
price Float Sí Precio unitario de la variante.
metadata Object No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplos de REST API

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

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

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

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

Posprocesamiento de eventos de comercio electrónico

Cuando envías un evento de comercio electrónico, Braze lo valida contra el esquema esperado para ese nombre de evento.

La siguiente tabla resume lo que Braze hace automáticamente para cada evento cuando la validación es exitosa. Para saber qué sucede cuando la validación falla, consulta Validación de eventos y solución de problemas.

Evento Qué hace Braze automáticamente
ecommerce.order_placed Incrementa Total Revenue en total_value y Total Orders en 1 en el perfil de usuario.
ecommerce.order_cancelled Decrementa Total Orders en 1.
ecommerce.order_refunded Decrementa Total Revenue en total_value e incrementa Total Refund Value.
ecommerce.cart_updated Crea o actualiza el objeto de mapeado de carritos en el perfil de usuario (cargas útiles de carrito completo o actualizaciones incrementales del carrito con action opcional: add, remove o replace). El carrito expira después de 30 días sin una actualización.
ecommerce.product_viewed Sin cambios en el perfil de usuario. Disponible para segmentación, desencadenantes y características de BrazeAITM (como recomendaciones de artículos).
ecommerce.checkout_started Sin cambios en el perfil de usuario. Disponible para segmentación y desencadenantes (por ejemplo, flujos de pago abandonado).

Implementar eventos de comercio electrónico

Puedes enviar eventos de comercio electrónico a través del punto de conexión /users/track (del lado del servidor) o del método del SDK del cliente logCustomEvent.

Enviar eventos del lado del servidor

Usa el punto de conexión /users/track para enviar eventos de comercio electrónico desde tu backend. Cada evento requiere el nombre exacto del evento, el external_id del usuario y un objeto de propiedades que coincida con el esquema del evento.

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

POST /users/track

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

Puntos de datos y facturación

Los eventos de comercio electrónico no consumen puntos de datos. Puedes registrarlos sin ningún impacto en tu uso de puntos de datos.

Límite de tamaño de eventos

Las propiedades de eventos enviadas a /users/track tienen un límite de 102 400 bytes (100 KB) por evento. Para mensajes desencadenados de Campaigns y Canvas, las trigger_properties enviadas a /campaigns/trigger/send y /canvas/trigger/send tienen un límite predeterminado más estricto de 51 200 bytes (50 KB).

Como práctica recomendada, envía solo la información de producto que necesitas para desencadenar, personalizar o atribuir el evento. Almacena detalles de producto más ricos, como descripciones, listas completas de variantes, inventario o imágenes alternativas, en los Catálogos de Braze. Haz referencia a estos detalles por product_id o variant_id al enviar mensajes. Usa el objeto metadata de forma selectiva para el contexto específico del pedido o producto que la mensajería utilizará.

Manejo de moneda

Braze convierte automáticamente los valores de moneda que no sean USD a USD usando el tipo de cambio de la fecha en que se reporta el evento. Este valor convertido es el que aparece en las métricas de ingresos.

Campo de fuente

La propiedad de fuente es una cadena obligatoria que identifica de dónde se originó el evento. Por ejemplo, shopify, in-store POS o custom_api. Esto te ayuda a distinguir las fuentes de integración al analizar datos en exportaciones de Currents o al depurar problemas de validación.

Flexibilidad de metadatos

Tanto los objetos de metadatos a nivel de evento como a nivel de producto aceptan pares clave-valor arbitrarios, por lo que puedes adjuntar dimensiones personalizadas sin modificar el esquema principal. Ejemplos comunes incluyen order_status_url, gift_wrapped, loyalty_points_earned o warehouse_id. Estas propiedades están disponibles en la personalización con Liquid, las exportaciones de Currents y la segmentación a través de Extensiones de segmento.

Validación de eventos y solución de problemas

Cuando envías un evento recomendado de comercio electrónico a través de /users/track o cualquier SDK de Braze, Braze valida la carga útil contra el esquema JSON del evento durante el procesamiento del evento recomendado. La validación se ejecuta automáticamente en cada evento cuyo nombre coincida exactamente con un evento recomendado (por ejemplo, ecommerce.order_placed o ecommerce.cart_updated).

Qué validamos

Para cada evento cuyo nombre coincida con un evento recomendado de comercio electrónico, Braze verifica:

Verificación Ejemplo
Nombre del evento Debe ser exacto. Por ejemplo, ecommerce.cart_updated es correcto, no ecommerce.Cart_Updated, cartupdated ni cart_updated.
Propiedades obligatorias presentes order_placed requiere order_id, total_value, currency, products y source.
Tipos de datos correctos total_value debe ser un número; currency debe ser una cadena; products debe ser un array.
Sin propiedades adicionales de nivel superior Los campos personalizados bajo propiedades causan un fallo. Usa el objeto metadata en su lugar.
Restricciones de valores Los campos monetarios deben ser ≥ 0. currency debe ser una cadena ISO 4217 válida.
Campos por producto Cada elemento en products[] debe incluir product_id, product_name, variant_id, quantity y price.

Por qué validamos

Los eventos de comercio electrónico alimentan características que dependen de datos consistentes y predecibles, incluyendo el seguimiento de ingresos, la etiqueta de Liquid {% shopping_cart %}, el desencadenante de carrito abandonado y los informes. Cuando las cargas útiles se desvían del esquema, estas características producen inexactitudes silenciosas (totales de ingresos incorrectos, carritos faltantes, desencadenantes rotos). La validación aplica el contrato de forma anticipada para que las características posteriores se comporten de manera predecible.

Cuando la validación es exitosa

El evento se procesa como un evento recomendado de comercio electrónico con todo el posprocesamiento asociado. Consulta Esquemas de eventos para la lista completa de comportamientos desencadenados por cada tipo de evento.

Verificar un evento exitoso

Después de enviar un evento, puedes confirmar que fue aceptado y procesado correctamente usando cualquiera de los siguientes métodos:

  • Registro de eventos de usuario: Abre el perfil del usuario en el dashboard y revisa su actividad. Los eventos recomendados aparecen con su carga útil completa de propiedades, para que puedas confirmar que el evento llegó y que los valores coinciden con lo que enviaste.
  • Informe de eventos personalizados: Ve a Analytics > Custom Events para ver los conteos agregados de cada evento recomendado a lo largo del tiempo. Esto es útil para confirmar que el tráfico de producción fluye como se espera cuando tu integración está en vivo.
  • Usuarios de prueba: Marca a un usuario en tu espacio de trabajo de desarrollo como usuario de prueba, luego desencadena eventos desde tu integración contra ese usuario. Los usuarios de prueba están marcados en el dashboard, lo que facilita aislar e inspeccionar el comportamiento de extremo a extremo.

Cuando la validación falla

El evento no se procesa como un evento recomendado. Específicamente:

  • El evento se descarta por completo. Los eventos recomendados de comercio electrónico no válidos no se registran en el perfil de usuario, no aparecen en Currents y no están disponibles para segmentación.
  • Las características posteriores de eventos recomendados no se ejecutan, incluyendo:
    • Seguimiento de ingresos (informes de ingresos, campos calculados del usuario como total_revenue)
    • Actualizaciones del objeto de carrito en el perfil de usuario
    • Desencadenantes “Perform Cart Updated Event” o “Placed Order” en Canvas y Campaigns

La forma en que se reportan los errores depende de la ruta de ingesta:

  • REST API (/users/track): Cada evento no válido se reporta en el array de errores de la respuesta. Cada entrada te indica qué evento falló (índice) y por qué (tipo). El campo message de nivel superior aún dice “success”, lo que solo significa que tu solicitud llegó a Braze, no que cada evento fuera válido. Siempre verifica si hay un array de errores en la respuesta.
  • SDK de Braze: Las llamadas del SDK retornan inmediatamente y la validación se ejecuta en segundo plano, por lo que los errores no se envían de vuelta a tu aplicación. Para enterarte de los fallos de validación de eventos de comercio electrónico, busca el correo electrónico de resumen de fallos (consulta Encontrar fallos).

Ejemplo de respuesta de error de la API

El punto de conexión /users/track devuelve errores a nivel de campo que indican qué propiedades fallaron y por qué. Ten en cuenta que el message de nivel superior puede devolver "success" porque el evento fue aceptado en el pipeline; el array errors te indica qué campos fallaron en la validación del esquema. Consulta el siguiente ejemplo de respuesta de error.

1
2
3
4

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

Los fallos también se clasifican internamente y se agregan para el correo electrónico de resumen de fallos:

Tipo de fallo Significado Ejemplo
missing_property Falta un campo obligatorio. order_placed enviado sin order_id.
extra_property Se agregó un campo que el esquema no define. Un campo personalizado gift_wrapped en el nivel superior de properties en lugar de dentro de metadata.
unexpected_data_type Un campo tiene el tipo incorrecto. total_value: "29.99" (cadena) en lugar de 29.99 (número).

Encontrar fallos

Braze envía por correo electrónico a los administradores de tu espacio de trabajo un resumen de los fallos de validación de eventos recomendados para que puedas identificar y corregir problemas de integración sin monitorear manualmente cada evento.

El correo electrónico de resumen incluye:

  • Conteo total de errores: Conteos de errores para el período de reporte.
  • Errores por evento: Un desglose de cuántos eventos fallaron para cada tipo de evento recomendado (por ejemplo, ecommerce.cart_updated y ecommerce.order_placed). Usa esto para identificar qué eventos de tu integración necesitan atención primero.
  • Errores por fuente: Una división entre API y SDK, para que puedas identificar qué integración está generando los fallos.

Si no estás recibiendo estos correos electrónicos o deseas verificar la lista de destinatarios, ponte en contacto con tu equipo de cuenta de Braze.

Diagnosticar y corregir fallos

Cuando recibas un correo electrónico de resumen de fallos:

  1. Identifica el evento que falla y la fuente. El correo electrónico separa los fallos por nombre de evento y fuente de integración (sdk versus rest_api), para que puedas identificar qué integración necesita la corrección. Si tienes múltiples fuentes enviando el mismo evento (por ejemplo, el SDK de tu tienda y un webhook de backend ambos enviando cart_updated), abórdalos de forma independiente.
  2. Compara tu carga útil con el esquema en Esquemas de eventos. La mayoría de los fallos caen en uno de tres patrones:
    • missing_property: Falta un campo obligatorio. Para resolverlo, agrega el campo obligatorio.
    • extra_property: Un campo personalizado está en el nivel superior de properties. Para resolverlo, mueve el campo personalizado dentro de metadata (a nivel de evento) o products[].metadata (por producto).
    • unexpected_data_type: Un valor tiene el tipo incorrecto (por ejemplo, total_value enviado como cadena). Para resolverlo, convierte el valor antes de enviarlo.
  3. Prueba la carga útil corregida en un espacio de trabajo de desarrollo antes de implementarla en producción. Envía un evento de prueba conocido para un usuario de prueba, luego verifica el comportamiento esperado del evento recomendado en el perfil de ese usuario (por ejemplo, que el objeto de carrito se actualice, que los ingresos se incrementen o que el desencadenante de carrito abandonado se active).
  4. Monitorea el siguiente correo electrónico de fallos para confirmar que el conteo de fallos para ese evento, fuente y tipo baja a cero.

Para los requisitos completos de propiedades por evento, consulta Esquemas de eventos.
New Stuff!