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 acciones desencadenantes basadas en acciones dedicadas para Campaigns y Canvas.
Eventos recomendados de comercio electrónico
Los eventos recomendados de comercio electrónico cubren seis pasos del 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 Ingresos totales, Pedidos totales y Reembolsos totales. También puedes crear Segments con filtrado anidado por propiedades de producto mediante extensiones de segmento, personalizar mensajes de carrito abandonado con la etiqueta de Liquid {% shopping_cart %} y alimentar capacidades de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos, entre otras capacidades.
Como estos eventos siguen un esquema definido, cada característica compatible puede leer los datos estructurados sin que tengas que hacer un mapeado de propiedades personalizado ni una configuración específica para cada característica.
El evento de compra heredado está entrando en modo de mantenimiento. Los clientes existentes de Braze pueden seguir utilizando los eventos de compra heredados. Seguirán funcionando como se espera, pero las nuevas funcionalidades se desarrollarán sobre los eventos recomendados de comercio electrónico en adelante. Braze proporcionará un aviso previo con suficiente antelación antes de que se establezca cualquier fecha de fin de vida. Los nuevos clientes de Braze deben utilizar los eventos recomendados de comercio electrónico, ya que los eventos de compra heredados no estarán disponibles.
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 mediante el SDK de Braze, el endpoint de la REST API /users/track, la ingesta de datos en la nube (CDI) o la importación de CSV, y Braze valida cada evento con su esquema durante la ingesta. Cuando la validación se supera, Braze aplica automáticamente el posprocesamiento específico de ese tipo de evento, como calcular los campos de ingresos y gestionar el estado del carrito en los perfiles de usuario.
Los eventos de comercio electrónico funcionan en cualquier lugar donde funcionen otros eventos personalizados: desencadenantes y filtros de eventos personalizados realizados, informes de eventos personalizados y más. Sin embargo, su validación de esquema desbloquea capacidades adicionales, entre ellas:
- Acciones desencadenantes “Realiza un pedido” en Campaigns, Canvas, pasos de Rutas de Acción, desencadenantes de mensajes dentro de la aplicación y eliminación de tarjetas de contenido
- Campos calculados de comercio electrónico en el perfil de usuario (Ingresos totales, Pedidos totales, Reembolsos totales)
- Gestión del estado del carrito para flujos de carrito abandonado
- Datos más completos para 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 su nombre en cualquier lugar donde la plataforma admita eventos personalizados. Por ejemplo, puedes desencadenar una campaña basada en acciones con eventos ecommerce.product_viewed, crear un Segment que filtre por eventos ecommerce.checkout_started o exportar eventos ecommerce.order_placed mediante 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 el nombre de un evento no coincide exactamente con uno de los seis nombres canónicos, Braze lo trata como un evento personalizado estándar y no se aplica ningún posprocesamiento de comercio electrónico.
No puedes personalizar ni cambiar el nombre de los 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 las etapas del recorrido de compra. Dispara cada evento en el momento en que el usuario complete la acción correspondiente.
Los ejemplos de las siguientes pestañas muestran la carga útil de la REST API para cada evento.
Para el registro del lado del cliente, ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started y ecommerce.order_placed usan las API de eventos de comercio electrónico del SDK cuando están disponibles, mientras que ecommerce.order_cancelled y ecommerce.order_refunded usan logCustomEvent.
Los eventos de reembolso y cancelación suelen enviarse desde tu servidor a través de la REST API de Braze, ya que normalmente dependen de que finalice una lógica del lado del servidor, como tu flujo de reembolsos. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Se desencadena cuando un usuario ve la página de detalles de un producto. Este evento es compatible con las notificaciones de vuelta a existencias y las notificaciones de bajada de precio de los catálogos de Braze.
Implementación del lado del cliente
Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Propiedades del evento
| Nombre de la propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto (por ejemplo, SKU o ID del artículo). |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante del producto (por ejemplo, shirt_medium_blue). |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto para obtener más detalles. |
price |
Flotante | Sí | Precio unitario de la variante en el momento de la visualización. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras (por ejemplo, USD o EUR). |
source |
Cadena | Sí | Origen del evento (por ejemplo, web, ios o android). |
type |
Matriz de cadenas | No | Obligatorio para usar las características de desencadenantes de catálogo de Braze para alertas de vuelta a existencias y de bajada de precio. Valores aceptados: "price_drop", "back_in_stock". |
catalog_name |
Cadena | No | El catálogo al que pertenece una suscripción de vuelta a existencias o de bajada de precio creada a partir de este evento. Si se omite, se usa el catálogo alternativo del espacio de trabajo. Debe ser una propiedad de nivel superior; se ignora un catalog_name anidado dentro de metadata. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, category o brand). |
Ejemplo de REST API
{
"events": [
{
"external_id": "user_98765",
"name": "ecommerce.product_viewed",
"time": "2026-04-28T14:22:11Z",
"properties": {
"product_id": "SKU-RUN-4821",
"product_name": "Ultraboost Running Shoe",
"variant_id": "UB-BLK-11",
"image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
"product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
"price": 189.99,
"currency": "USD",
"source": "web",
"type": ["price_drop", "back_in_stock"],
"catalog_name": "running_shoes",
"metadata": {
"category": "Running Shoes",
"brand": "Shoe Brand"
}
}
}
]
}
Se desencadena cada vez que cambia el contenido del carrito de un usuario.
Implementación del lado del cliente
Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Puedes enviar este evento de una de estas dos formas:
- Reemplazo completo del carrito: Omite
actiono estableceactionenreplace. Incluye el conjunto completo de líneas de pedido enproductscon cantidades absolutas (unidades totales por variante en el carrito). Debes incluirtotal_value. - Actualizaciones incrementales del carrito: Establece
actionenaddoremove. Incluye solo las líneas de pedido que hayan cambiado. Cadaquantityes el número de unidades que se añaden o eliminan, no la cantidad total en el carrito.- Con
add, Braze aumenta la cantidad de la línea o añade una línea nueva. Conremove, Braze reduce la cantidad de la línea y la elimina cuando la cantidad llega a0. - Con
addyremove,total_valuees opcional y no se almacena en el carrito; para un carrito actualizado solo conaddoremove, la etiqueta{% shopping_cart %}devuelve en su lugar la suma delpricede cada producto multiplicado por suquantity.
- Con
Usa actualizaciones incrementales del carrito (add o remove) o el reemplazo completo (sin action o con replace) para un carrito determinado. No se recomienda combinar ambos métodos para el mismo cart_id, ya que puede provocar un estado del carrito incoherente en Braze.
Para desencadenar mensajería a partir de este evento, usa el desencadenante Realizar evento de actualización del carrito en Canvas y Campaigns. Este desencadenante incluye un tratamiento especial para evitar que el carrito avance por el embudo de compra.
El carrito crea un objeto de mapeado de carritos en el perfil de usuario que impulsa la etiqueta de Liquid {% shopping_cart %}. El carrito caduca tras 30 días sin actualizaciones y se elimina cuando se procesa el siguiente evento de comercio electrónico del usuario. Si se fusionan dos perfiles de usuario, Braze conserva ambos carritos.
ID del carrito después del pago o del pedido
Después de que Braze reciba ecommerce.checkout_started o ecommerce.order_placed para un cart_id, ese carrito deja de tratarse como abandonado:
- Los futuros eventos
ecommerce.cart_updatedcon el mismocart_idno desencadenan Realizar evento de actualización del carrito - La etiqueta
{% shopping_cart %}se cancela de forma predeterminada - Después de
ecommerce.order_placed, los productos del carrito se borran y las actualizaciones posteriores del carrito para esecart_idse ignoran hasta que el carrito caduque
Genera un nuevo cart_id cuando el comprador inicie un carrito nuevo.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
cart_id |
Cadena | Sí | Identificador único del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. No reutilices un cart_id después de ecommerce.checkout_started o ecommerce.order_placed; consulta ID del carrito después del pago o del pedido. |
action |
Cadena | No | add (aumenta la cantidad o añade una línea), remove (reduce la cantidad; la línea se elimina al llegar a 0) o replace (reemplazo completo del carrito, igual que omitir action). |
total_value |
Flotante | Condicional | Obligatorio cuando se omite action o es replace, y se almacena como total del carrito. Opcional cuando action es add o remove.Cuando action es add o remove, el valor no se almacena en el carrito y no borra un total almacenado previamente. Cuando un carrito se actualiza solo con add o remove, no se almacena ningún total_value y la etiqueta {% shopping_cart %} suma el price de cada producto multiplicado por su quantity. |
subtotal_value |
Flotante | No | Valor del subtotal del carrito (después de descuentos, antes de impuestos y envío). No se almacena en el carrito y no está disponible mediante la etiqueta de Liquid {% shopping_cart %}. |
tax |
Flotante | No | Impuestos totales aplicados al carrito. No se almacena en el carrito y no está disponible mediante la etiqueta de Liquid {% shopping_cart %}. |
shipping |
Flotante | No | Coste total de envío del carrito. No se almacena en el carrito y no está disponible mediante la etiqueta de Liquid {% shopping_cart %}. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
products |
Matriz | Sí | Líneas de pedido de esta actualización. Para el reemplazo completo (sin action o con replace), incluye el carrito completo con cantidades absolutas. Para add o remove, incluye solo las líneas que hayan cambiado; consulta las propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles para datos adicionales a nivel de evento. |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Para el reemplazo completo (sin action o con replace), unidades de esta línea en el carrito. Para add o remove, cuántas unidades se añaden o eliminan. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Se desencadena cuando el usuario inicia el flujo de pago (por ejemplo, selecciona “Pagar” o llega a la página de pago).
Implementación del lado del cliente
Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Propiedades del evento
| Propiedad | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| checkout_id | Cadena | Sí | Identificador único de la sesión de pago. |
| cart_id | Cadena | No | Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. |
| total_value | Flotante | Sí | Valor monetario total del pago. |
| subtotal_value | Flotante | No | Valor del subtotal (después de descuentos, antes de impuestos y envío). |
| tax | Flotante | No | Impuestos totales aplicados al pago. |
| shipping | Flotante | No | Coste total de envío. |
| currency | Cadena | Sí | Código ISO 4217 de tres letras. |
| products | Matriz | Sí | Artículos que se están pagando. Consulta la subtabla de propiedades del producto. |
| source | Cadena | Sí | Origen del evento. |
| metadata | Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: checkout_url (Cadena) |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el carrito. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color, talla). |
Ejemplo de 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"
}
}
}
]
}
Se desencadena cuando un pedido se completa correctamente o se confirma el pago.
Implementación del lado del cliente
Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Este evento es el principal impulsor de ingresos. Incrementa total_revenue en el valor de total_value e incrementa total_orders en 1 en el perfil de usuario.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido. |
cart_id |
Cadena | No | Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario. |
total_value |
Flotante | Sí | Valor monetario total del pedido. |
subtotal_value |
Flotante | No | Valor del subtotal (después de descuentos, antes de impuestos y envío). |
tax |
Flotante | No | Impuestos totales aplicados al pedido. |
shipping |
Flotante | No | Coste total de envío. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados al pedido. |
discounts |
Matriz | No | Lista detallada de los descuentos aplicados. |
products |
Matriz | Sí | Artículos del pedido. Consulta la subtabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena) |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el carrito. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Ejemplo de 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"
}
}
}
]
}
Se desencadena cuando se cancela un pedido.
Implementación del lado del cliente
Usa logCustomEvent. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Este evento reduce total_orders en 1 en el perfil de usuario. No afecta a total_revenue; usa order_refunded para ajustar los ingresos.
Propiedades del evento
| Propiedad | Tipo | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido. |
total_value |
Flotante | Sí | Valor monetario total del pedido que se cancela. Debe ser ≥ 0: envía el importe absoluto; Braze se encarga de la reducción. |
subtotal_value |
Flotante | No | Valor del subtotal (después de descuentos, antes de impuestos y envío). |
tax |
Flotante | No | Impuestos totales aplicados al pedido. |
shipping |
Flotante | No | Coste total de envío. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados al pedido. |
discounts |
Matriz | No | Lista detallada de los descuentos aplicados. |
cancel_reason |
Cadena | Sí | Motivo por el que se canceló el pedido. |
products |
Matriz | Sí | Artículos del pedido cancelado. Consulta la subtabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena) |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el carrito. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Ejemplo de 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"
}
}
}
]
}
Se desencadena cuando se emite un reembolso total o parcial.
Implementación del lado del cliente
Usa logCustomEvent. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el SDK de Braze.
Este evento reduce total_revenue en el valor de total_value e incrementa total_refunds en el perfil de usuario. Para reembolsos parciales, establece total_value solo en el importe reembolsado, no en el total del pedido original.
Propiedades del evento
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
order_id |
Cadena | Sí | Identificador único del pedido original. |
total_value |
Flotante | Sí | Valor monetario total del reembolso. Debe ser ≥ 0: envía el importe absoluto; Braze se encarga del incremento de total_refunds. |
currency |
Cadena | Sí | Código ISO 4217 de tres letras. |
total_discounts |
Flotante | No | Importe total de los descuentos aplicados originalmente. |
discounts |
Matriz | No | Lista detallada de los descuentos. |
products |
Matriz | Sí | Artículos que se reembolsan. Consulta la subtabla de propiedades del producto. |
source |
Cadena | Sí | Origen del evento. |
metadata |
Objeto | No | Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (Cadena). |
Propiedades del producto (products[])
| Propiedad | Tipo de datos | Obligatorio | Descripción |
|---|---|---|---|
product_id |
Cadena | Sí | Identificador único del producto. |
product_name |
Cadena | Sí | Nombre visible del producto. |
variant_id |
Cadena | Sí | Identificador de la variante. |
image_url |
Cadena | No | URL de la imagen del producto. |
product_url |
Cadena | No | URL de la página del producto. |
quantity |
Entero | Sí | Número de unidades en el carrito. |
price |
Flotante | Sí | Precio unitario de la variante. |
metadata |
Objeto | No | Pares clave-valor flexibles (por ejemplo, color o size). |
Ejemplos de REST API
{
"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"
}
}
}
]
}
Posprocesamiento de eventos de comercio electrónico
Cuando envías un evento de comercio electrónico, Braze lo valida con el esquema esperado para ese nombre de evento.
La siguiente tabla resume lo que Braze hace automáticamente con cada evento cuando se supera la validación. Para saber qué ocurre cuando la validación falla, consulta Validación de eventos y solución de problemas.
| Evento | Lo que Braze hace automáticamente |
|---|---|
ecommerce.order_placed |
Incrementa Ingresos totales en total_value y Pedidos totales en 1 en el perfil de usuario. |
ecommerce.order_cancelled |
Reduce Pedidos totales en 1. |
ecommerce.order_refunded |
Reduce Ingresos totales en total_value e incrementa Valor total de reembolsos. |
ecommerce.cart_updated |
Crea o actualiza el objeto de mapeado de carritos en el perfil de usuario (cargas útiles con el carrito completo o actualizaciones incrementales del carrito con action opcional: add, remove o replace). El carrito caduca tras 30 días sin actualizaciones. |
ecommerce.product_viewed |
No modifica el perfil de usuario. Disponible para segmentación, desencadenamiento y características de BrazeAITM (como las recomendaciones de artículos). |
ecommerce.checkout_started |
No modifica el perfil de usuario. Disponible para segmentación y desencadenamiento (por ejemplo, flujos de pago abandonado). |
Los valores en monedas distintas del USD se convierten automáticamente a USD con el tipo de cambio de la fecha en que se notifica el evento. Si ya informas en USD, fija USD como moneda para evitar conversiones no deseadas.
Detalles de implementación
Puntos de datos y facturación
Los eventos de comercio electrónico no consumen puntos de datos. Puedes registrarlos sin que afecte a tu uso de puntos de datos.
Límite de tamaño de los eventos
Las propiedades del evento enviadas a /users/track tienen un límite de 102 400 bytes (100 KB) por evento. Para los mensajes desencadenados de campañas 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 del producto que necesites para desencadenar, personalizar o atribuir el evento. Almacena los detalles más completos del producto (como descripciones, listas completas de variantes, inventario o imágenes alternativas) en los catálogos de Braze. Haz referencia a estos detalles mediante product_id o variant_id al enviar mensajes. Usa el objeto metadata de forma selectiva para el contexto específico del pedido o del producto que vaya a usar la mensajería.
Gestión de divisas
Braze convierte automáticamente los valores en divisas distintas del USD a USD usando el tipo de cambio de la fecha en que se notifica el evento. Este valor convertido es el que aparece en las métricas de ingresos.
Si solo operas en USD, codifica "currency": "USD" en cada evento para evitar conversiones innecesarias.
Campo de origen
La propiedad de origen es una cadena obligatoria que identifica 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 los datos en las exportaciones de Currents o al depurar problemas de validación.
Flexibilidad de los metadatos
Tanto el objeto de metadatos a nivel de evento como el de nivel de producto aceptan pares clave-valor arbitrarios, por lo que puedes añadir dimensiones personalizadas sin modificar el esquema principal. Algunos ejemplos habituales son order_status_url, gift_wrapped, loyalty_points_earned o warehouse_id. Estas propiedades están disponibles en la personalización con Liquid, en las exportaciones de Currents y en la segmentación mediante extensiones de segmento.
Los eventos recomendados usan un esquema estricto. Por ello, añadir propiedades personalizadas en el nivel superior de las propiedades hará que no se supere la validación. Coloca todas las propiedades personalizadas dentro del objeto metadata a nivel de evento o del objeto metadata a nivel de producto dentro de products[]. Estas siguen estando disponibles para Liquid, Currents y la segmentación, igual que los campos de nivel superior.
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 de cualquier SDK de Braze, Braze valida la carga útil con el esquema JSON del evento mientras procesa el 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
En cada evento cuyo nombre coincida con un evento recomendado de comercio electrónico, Braze comprueba lo siguiente:
| Comprobación | Ejemplo |
|---|---|
| Nombre del evento | Debe ser exacto. Por ejemplo, ecommerce.cart_updated es correcto, pero 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 una matriz. |
| Sin propiedades adicionales de nivel superior | Los campos personalizados dentro de properties provocan un error. 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 de products[] debe incluir product_id, product_name, variant_id, quantity y price. |
Por qué validamos
Los eventos de comercio electrónico impulsan características que dependen de datos coherentes y predecibles, como el seguimiento de ingresos, la etiqueta de Liquid {% shopping_cart %}, el desencadenante de carrito abandonado y los informes. Cuando las cargas útiles no se ajustan al esquema, estas características generan imprecisiones silenciosas (totales de ingresos incorrectos, carritos que faltan, desencadenantes que no funcionan). La validación aplica el contrato desde el principio para que las características posteriores se comporten de forma predecible.
Cuando la validación se supera
El evento se procesa como un evento recomendado de comercio electrónico con todo el procesamiento posterior asociado. Consulta Eventos recomendados de comercio electrónico para ver la lista completa de comportamientos que desencadena cada tipo de evento.
Verificar un evento correcto
Después de enviar un evento, puedes confirmar que se aceptó y se procesó correctamente con cualquiera de las siguientes opciones:
- Registro de usuarios del evento: Abre el perfil del usuario en el panel y revisa su actividad. Los eventos recomendados aparecen con su carga útil completa de propiedades, así que puedes confirmar que el evento llegó y que los valores coinciden con lo que enviaste.
- Informe de eventos personalizados: Ve a Análisis > Informe de eventos personalizados para ver los recuentos agregados de cada evento recomendado a lo largo del tiempo. Esto es útil para confirmar que el tráfico de producción fluye como esperas cuando tu integración está en vivo.
- Usuarios de prueba: Marca a un usuario de tu espacio de trabajo de desarrollo como usuario de prueba y, a continuación, desencadena eventos desde tu integración para ese usuario. Los usuarios de prueba aparecen marcados en el panel, 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. En concreto:
- El evento se descarta por completo. Los eventos recomendados de comercio electrónico no válidos no llegan al perfil de usuario, no aparecen en Currents y no están disponibles para la segmentación.
- No se ejecutan las características posteriores de los eventos recomendados, entre ellas:
- Seguimiento de ingresos (informes de ingresos, campos calculados del usuario como
total_revenue) - Actualizaciones del objeto de carrito en el perfil de usuario
- Desencadenantes Actualizar carrito o Realizar pedido en Canvas y Campaigns
- Seguimiento de ingresos (informes de ingresos, campos calculados del usuario como
La forma en que se informan los errores depende de la ruta de ingesta:
- REST API (
/users/track): Cada evento no válido se informa en la matriz de errores de la respuesta. Cada entrada te indica qué evento falló (índice) y por qué (tipo). El campo de mensaje de nivel superior sigue diciendo “success”, lo que solo significa que tu solicitud llegó a Braze, no que todos los eventos fueran válidos. Comprueba siempre si hay una matriz de errores en la respuesta. - SDK de Braze: Las llamadas al SDK se devuelven de inmediato y la validación se ejecuta en segundo plano, así 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, presta atención al correo electrónico de resumen de fallos (consulta Encontrar fallos).
Ejemplo de respuesta de error de la API
El endpoint /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 se aceptó en la canalización; la matriz errors te indica qué campos no superaron la validación del esquema. Consulta el siguiente ejemplo de respuesta de error.
{
"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 añadió 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). |
Los nombres de eventos que no coinciden exactamente con un evento recomendado (por ejemplo, ecommerce.OrderPlaced) omiten la validación por completo y se registran como eventos personalizados normales. Aparecen en Currents y en la segmentación con el nombre que enviaste, pero no reciben el procesamiento de eventos recomendados ni ninguna entrada en errors en la respuesta.
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 supervisar manualmente cada evento.
El correo electrónico de resumen incluye:
- Recuento total de errores: Recuentos de errores del periodo del informe.
- Errores por evento: Un desglose de cuántos eventos fallaron por cada tipo de evento recomendado (por ejemplo,
ecommerce.cart_updatedyecommerce.order_placed). Úsalo para identificar qué eventos de tu integración necesitan atención primero. - Errores por origen: Una división entre API y SDK, para que puedas localizar qué integración genera los fallos.
Si no recibes estos correos electrónicos o quieres verificar la lista de destinatarios, ponte en contacto con el equipo de tu cuenta de Braze.
Diagnosticar y corregir fallos
Cuando recibas un correo electrónico de resumen de fallos:
- Identifica el evento y el origen que fallan. El correo electrónico separa los fallos por nombre de evento y origen de la integración (
sdkfrente arest_api), para que puedas localizar qué integración necesita la corrección. Si tienes varios orígenes que envían el mismo evento (por ejemplo, el SDK de tu tienda online y un webhook de backend que envíancart_updated), abórdalos por separado. - Compara tu carga útil con el esquema en Esquemas de eventos. La mayoría de los fallos siguen uno de estos tres patrones:
missing_property: Falta un campo obligatorio. Para solucionarlo, añade el campo obligatorio.extra_property: Hay un campo personalizado en el nivel superior deproperties. Para solucionarlo, mueve el campo personalizado dentro demetadata(a nivel de evento) o deproducts[].metadata(por producto).unexpected_data_type: Un valor tiene el tipo incorrecto (por ejemplo,total_valueenviado como cadena). Para solucionarlo, convierte el valor antes de enviarlo.
- 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 y, a continuación, 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 aumenten o que se active el desencadenante de carrito abandonado).
- Supervisa el siguiente correo electrónico de fallos para confirmar que el recuento de fallos de ese evento, origen y tipo baja a cero.
Para conocer todos los requisitos de propiedades de cada evento, consulta Esquemas de eventos.