Eventos recomendados

Os eventos recomendados são construídos sobre um framework que envia eventos personalizados padronizados com esquemas JSON definidos. Quando você envia um evento recomendado, a Braze o valida em relação ao seu esquema na ingestão e aplica processamento especializado, como cálculos automáticos de campos ou gerenciamento de carrinho, que eventos personalizados genéricos não recebem. Para determinados conjuntos de eventos do setor, a Braze também oferece tratamento especial, como gatilhos dedicados baseados em ação para Campaigns e Canvas.

Eventos recomendados de eCommerce

Os eventos recomendados de eCommerce cobrem seis etapas da jornada de compra: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled e order_refunded. Quando você envia esses eventos, a Braze valida os dados e os disponibiliza para um conjunto crescente de recursos da plataforma.

Esses recursos incluem modelos de Canvas para fluxos de navegação abandonada, carrinho abandonado, checkout abandonado e confirmação de pedido; relatórios de eCommerce; e campos calculados no perfil do usuário para Total Revenue, Total Orders e Total Refunds. Você também pode criar Segments com filtragem aninhada de propriedades de produto por meio de extensões de segmento, personalizar mensagens de carrinho abandonado com a Liquid tag {% shopping_cart %} e alimentar recursos do BrazeAI^TM, como Eventos preditivos, Churn preditivo e recomendações de itens, entre outros.

Como esses eventos seguem um esquema definido, cada recurso compatível consegue ler os dados estruturados sem que você precise mapear propriedades personalizadas ou fazer configurações específicas para cada recurso.

Importante

O evento de compra legado está entrando em modo de manutenção. Clientes existentes da Braze podem continuar usando eventos de compra legados. Eles continuarão funcionando como esperado, mas novas funcionalidades serão desenvolvidas com base nos eventos recomendados de eCommerce daqui em diante. A Braze fornecerá aviso prévio bem antes de qualquer data de fim de vida ser definida. Novos clientes da Braze devem usar os eventos recomendados de eCommerce, pois os eventos de compra legados não estarão disponíveis.

Como funcionam os eventos de eCommerce

Os eventos de eCommerce são eventos personalizados com nomes e esquemas de propriedades predefinidos. Você os envia usando o SDK da Braze, o endpoint /users/track da REST API, a Ingestão de dados na nuvem (CDI) ou a importação de CSV, e a Braze valida cada evento em relação ao seu esquema durante a ingestão. Quando a validação é aprovada, a Braze aplica automaticamente o pós-processamento específico daquele tipo de evento, como o cálculo dos campos de receita e o gerenciamento do estado do carrinho nos perfis de usuário.

Os eventos de eCommerce funcionam em todos os lugares onde os outros eventos personalizados funcionam: gatilhos e filtros de eventos personalizados realizados, relatórios de eventos personalizados e muito mais. No entanto, a validação do esquema libera recursos adicionais, incluindo:

• Ações-gatilho “Places order” em Campaigns, Canvas, etapas de jornadas de ação, gatilhos de mensagens no app e remoção de cartões de conteúdo
• Campos calculados de eCommerce no perfil do usuário (Total Revenue, Total Orders, Total Refunds)
• Gerenciamento do estado do carrinho para fluxos de carrinho abandonado
• Dados mais completos para recursos do BrazeAI^TM, como Eventos preditivos, Churn preditivo e recomendações de itens

Você também pode referenciar eventos de eCommerce pelo nome em qualquer lugar da plataforma que aceite eventos personalizados. Por exemplo, você pode disparar uma Campaign baseada em ação com eventos ecommerce.product_viewed, criar um Segment filtrando eventos ecommerce.checkout_started ou exportar eventos ecommerce.order_placed pelo Currents.

Nomenclatura de eventos

Os nomes de eventos são exatos, diferenciam maiúsculas de minúsculas e são separados por pontos. Sempre use o formato canônico. Se o nome de um evento não corresponder exatamente a um dos seis nomes canônicos, a Braze o trata como um evento personalizado padrão e nenhum pós-processamento de eCommerce acontece.

Não é possível personalizar nem renomear os eventos.

• Correto: ecommerce.order_placed
• Incorreto: order.placed, eCommerce_order_placed, Order_Placed

Esquemas de eventos

Os seis eventos recomendados de eCommerce correspondem às etapas da jornada de compra. Dispare cada evento no momento em que o usuário concluir a ação correspondente.

Dica

Os exemplos nas guias a seguir mostram a carga útil da REST API para cada evento.

Para registro no lado do cliente, ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started e ecommerce.order_placed usam as APIs de eventos de eCommerce do SDK quando disponíveis, enquanto ecommerce.order_cancelled e ecommerce.order_refunded usam logCustomEvent.

Os eventos de reembolso e cancelamento geralmente são enviados do seu servidor pela REST API da Braze, porque costumam depender da conclusão de uma lógica no servidor, como o seu fluxo de reembolso. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

• ecommerce.product_viewed
• ecommerce.cart_updated
• ecommerce.checkout_started
• ecommerce.order_placed
• ecommerce.order_cancelled
• ecommerce.order_refunded

Dispare quando um usuário visualizar a página de detalhes de um produto. Esse evento é compatível com as notificações de volta ao estoque e as notificações de queda de preço dos catálogos da Braze.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Nome da propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto (por exemplo, SKU ou ID do item).
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante do produto (por exemplo, shirt_medium_blue).
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto com mais detalhes.
price	Float	Sim	Preço unitário da variante no momento da visualização.
currency	String	Sim	Código ISO 4217 de três letras (por exemplo, USD ou EUR).
source	String	Sim	Origem do evento (por exemplo, web, ios ou android).
type	Array de strings	Não	Necessário para usar os recursos de gatilho de catálogo da Braze para alertas de volta ao estoque e queda de preço. Valores aceitos: "price_drop", "back_in_stock".
catalog_name	String	Não	O catálogo ao qual pertence uma inscrição de volta ao estoque ou queda de preço criada a partir desse evento. Se for omitido, será usado o catálogo de fallback do espaço de trabalho. Precisa ser uma propriedade de nível superior; um catalog_name aninhado em metadata é ignorado.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, category ou brand).

Exemplo 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"],
        "catalog_name": "running_shoes",
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Dispare sempre que o conteúdo do carrinho de um usuário mudar.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Você pode enviar esse evento de duas formas:

• Substituição completa do carrinho: Omita action ou defina action como replace. Inclua o conjunto completo de itens de linha em products com quantidades absolutas (total de unidades por variante no carrinho). É necessário incluir total_value.
• Atualizações incrementais do carrinho: Defina action como add ou remove. Inclua apenas os itens de linha que mudaram. Cada quantity é o número de unidades a adicionar ou remover, não a quantidade total no carrinho.
  • Com add, a Braze aumenta a quantidade da linha ou adiciona uma nova linha. Com remove, a Braze diminui a quantidade da linha e remove a linha quando a quantidade chega a 0.
  • Com add e remove, total_value é opcional e não fica armazenado no carrinho. Para um carrinho atualizado apenas com add ou remove, a tag {% shopping_cart %} retorna a soma do price de cada produto multiplicado pela sua quantity.

Aviso

Use atualizações incrementais do carrinho (add ou remove) ou a substituição completa (sem action ou com replace) para um determinado carrinho. Não recomendamos misturar as duas abordagens para o mesmo cart_id, pois isso pode deixar o estado do carrinho inconsistente na Braze.

Para disparar o envio de mensagens a partir desse evento, use o gatilho Perform Cart Updated Event em Canvas e Campaigns. Esse gatilho inclui um tratamento especial para impedir que o carrinho avance no funil de compra.

O carrinho cria um objeto de mapeamento de carrinhos no perfil do usuário, que alimenta a Liquid tag {% shopping_cart %}. O carrinho expira após 30 dias sem atualização e é removido quando o próximo evento de eCommerce do usuário é processado. Se dois perfis de usuário forem mesclados, a Braze preserva os dois carrinhos.

ID do carrinho após o checkout ou pedido

Depois que a Braze recebe ecommerce.checkout_started ou ecommerce.order_placed para um cart_id, esse carrinho deixa de ser tratado como abandonado:

• Eventos ecommerce.cart_updated futuros com o mesmo cart_id não disparam Perform Cart Updated Event
• A tag {% shopping_cart %} é interrompida por padrão
• Após ecommerce.order_placed, os produtos do carrinho são apagados e atualizações posteriores para esse cart_id são ignoradas até o carrinho expirar

Gere um novo cart_id quando o comprador iniciar um novo carrinho.

Propriedades do evento

Propriedade	Tipo de dados	Obrigatório	Descrição
cart_id	String	Sim	Identificador exclusivo do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário. Não reutilize um cart_id após ecommerce.checkout_started ou ecommerce.order_placed; consulte ID do carrinho após o checkout ou pedido.
action	String	Não	add (aumenta a quantidade ou adiciona uma linha), remove (diminui a quantidade; a linha é removida em 0) ou replace (substituição completa do carrinho, o mesmo que omitir action).
total_value	Float	Condicional	Obrigatório quando action é omitido ou é replace, e armazenado como o total do carrinho. Opcional quando action é add ou remove. Quando action é add ou remove, o valor não é armazenado no carrinho e não apaga um total armazenado anteriormente. Quando um carrinho é atualizado apenas com add ou remove, nenhum total_value é armazenado e a tag {% shopping_cart %} soma o price de cada produto multiplicado pela sua quantity.
subtotal_value	Float	Não	Valor subtotal do carrinho (após descontos, antes de impostos/frete). Não é armazenado no carrinho e não está disponível pela Liquid tag {% shopping_cart %}.
tax	Float	Não	Total de impostos aplicados ao carrinho. Não é armazenado no carrinho e não está disponível pela Liquid tag {% shopping_cart %}.
shipping	Float	Não	Custo total de frete do carrinho. Não é armazenado no carrinho e não está disponível pela Liquid tag {% shopping_cart %}.
currency	String	Sim	Código ISO 4217 de três letras.
products	Array	Sim	Itens de linha desta atualização. Para a substituição completa (sem action ou com replace), inclua o carrinho inteiro com quantidades absolutas. Para add ou remove, inclua apenas as linhas alteradas; consulte as propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Object	Não	Pares chave-valor flexíveis para dados adicionais no nível do evento.

Propriedades do produto (products[])

Propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto.
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante.
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto.
quantity	Integer	Sim	Para a substituição completa (sem action ou com replace), unidades desta linha no carrinho. Para add ou remove, quantas unidades adicionar ou remover.
price	Float	Sim	Preço unitário da variante.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, color ou size).

Dispare quando o usuário iniciar o fluxo de checkout (por exemplo, ao selecionar “Checkout” ou chegar à página de checkout).

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Propriedades do evento

Propriedade	Tipo	Obrigatório	Descrição
checkout_id	String	Sim	Identificador exclusivo da sessão de checkout.
cart_id	String	Não	Identificador do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário.
total_value	Float	Sim	Valor monetário total do checkout.
subtotal_value	Float	Não	Valor subtotal (após descontos, antes de impostos/frete).
tax	Float	Não	Total de impostos aplicados ao checkout.
shipping	Float	Não	Custo total de frete.
currency	String	Sim	Código ISO 4217 de três letras.
products	Array	Sim	Itens no checkout. Consulte a subtabela de propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Object	Não	Pares chave-valor flexíveis. Subpropriedade reconhecida: checkout_url (String)

Propriedades do produto (products[])

Propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto.
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante.
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto.
quantity	Integer	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, cor, tamanho).

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

Dispare quando um pedido for concluído com sucesso ou o pagamento for confirmado.

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK quando disponíveis. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse é o principal evento de receita. Ele aumenta total_revenue pelo valor em total_value e aumenta total_orders em 1 no perfil do usuário.

Propriedades do evento

Propriedade	Tipo de dados	Obrigatório	Descrição
order_id	String	Sim	Identificador exclusivo do pedido.
cart_id	String	Não	Identificador do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinho do usuário.
total_value	Float	Sim	Valor monetário total do pedido.
subtotal_value	Float	Não	Valor subtotal (após descontos, antes de impostos/frete).
tax	Float	Não	Total de impostos aplicados ao pedido.
shipping	Float	Não	Custo total de frete.
currency	String	Sim	Código ISO 4217 de três letras.
total_discounts	Float	Não	Valor total dos descontos aplicados ao pedido.
discounts	Array	Não	Lista detalhada dos descontos aplicados.
products	Array	Sim	Itens do pedido. Consulte a subtabela de propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Object	Não	Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto.
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante.
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto.
quantity	Integer	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, color ou size).

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

Dispare quando um pedido for cancelado.

Implementação no lado do cliente

Use logCustomEvent. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse evento diminui total_orders em 1 no perfil do usuário. Ele não afeta total_revenue; use order_refunded para ajustar a receita.

Propriedades do evento

Propriedade	Tipo	Obrigatório	Descrição
order_id	String	Sim	Identificador exclusivo do pedido.
total_value	Float	Sim	Valor monetário total do pedido cancelado. Precisa ser ≥ 0 — envie o valor absoluto; a Braze faz a redução.
subtotal_value	Float	Não	Valor subtotal (após descontos, antes de impostos/frete).
tax	Float	Não	Total de impostos aplicados ao pedido.
shipping	Float	Não	Custo total de frete.
currency	String	Sim	Código ISO 4217 de três letras.
total_discounts	Float	Não	Valor total dos descontos aplicados ao pedido.
discounts	Array	Não	Lista detalhada dos descontos aplicados.
cancel_reason	String	Sim	Motivo do cancelamento do pedido.
products	Array	Sim	Itens do pedido cancelado. Consulte a subtabela de propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Object	Não	Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto.
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante.
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto.
quantity	Integer	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, color ou size).

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

Dispare quando um reembolso total ou parcial for emitido.

Implementação no lado do cliente

Use logCustomEvent. Para ver exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse evento diminui total_revenue pelo valor em total_value e aumenta total_refunds no perfil do usuário. Para reembolsos parciais, defina total_value apenas como o valor reembolsado, não como o total original do pedido.

Propriedades do evento

Propriedade	Tipo de dados	Obrigatório	Descrição
order_id	String	Sim	Identificador exclusivo do pedido original.
total_value	Float	Sim	Valor monetário total do reembolso. Precisa ser ≥ 0 — envie o valor absoluto; a Braze faz o incremento em total_refunds.
currency	String	Sim	Código ISO 4217 de três letras.
total_discounts	Float	Não	Valor total dos descontos aplicados originalmente.
discounts	Array	Não	Lista detalhada dos descontos.
products	Array	Sim	Itens reembolsados. Consulte a subtabela de propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Object	Não	Pares chave-valor flexíveis. Subpropriedade reconhecida: order_status_url (String).

Propriedades do produto (products[])

Propriedade	Tipo de dados	Obrigatório	Descrição
product_id	String	Sim	Identificador exclusivo do produto.
product_name	String	Sim	Nome de exibição do produto.
variant_id	String	Sim	Identificador da variante.
image_url	String	Não	URL da imagem do produto.
product_url	String	Não	URL da página do produto.
quantity	Integer	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Object	Não	Pares chave-valor flexíveis (por exemplo, color ou size).

Exemplos de REST API

• reembolso total
• reembolso parcial

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

Pós-processamento de eventos de eCommerce

Quando você envia um evento de eCommerce, a Braze o valida em relação ao esquema esperado para aquele nome de evento.

A tabela a seguir resume o que a Braze faz automaticamente para cada evento quando a validação é aprovada. Para saber o que acontece quando a validação falha, consulte Validação de eventos e solução de problemas.

Importante

Valores em moedas diferentes de USD são convertidos automaticamente para USD usando a taxa de câmbio da data em que o evento é registrado. Se você já registra em USD, defina USD fixo como a moeda para evitar conversões indesejadas.

Detalhes da implementação

Pontos de dados e faturamento

Os eventos de eCommerce não consomem pontos de dados. Você pode registrá-los sem nenhum impacto no seu uso de pontos de dados.

Limite de tamanho do evento

As propriedades de evento enviadas para /users/track são limitadas a 102.400 bytes (100 KB) por evento. Para mensagens de Campaign e Canvas disparadas, as trigger_properties enviadas para /campaigns/trigger/send e /canvas/trigger/send têm um limite padrão mais rigoroso de 51.200 bytes (50 KB).

Como prática recomendada, envie apenas as informações de produto necessárias para disparar, personalizar ou atribuir o evento. Armazene detalhes mais completos do produto, como descrições, listas completas de variantes, estoque ou imagens alternativas, nos catálogos da Braze. Faça referência a esses detalhes pelo product_id ou variant_id ao enviar mensagens. Use o objeto metadata de forma seletiva, apenas para o contexto do pedido ou do produto que o envio de mensagens vai usar.

Tratamento de moedas

A Braze converte automaticamente valores em moedas diferentes de USD para USD, usando a taxa de câmbio da data em que o evento é relatado. Esse valor convertido é o que aparece nas métricas de receita.

Dica

Se você opera apenas em USD, defina "currency": "USD" de forma fixa em todos os eventos para evitar conversões desnecessárias.

Campo de origem

A propriedade de origem é uma string obrigatória que identifica de onde o evento se originou. Por exemplo, shopify, in-store POS ou custom_api. Isso ajuda você a distinguir as fontes de integração ao analisar dados em exportações do Currents ou ao depurar problemas de validação.

Flexibilidade dos metadados

Os objetos de metadados no nível do evento e no nível do produto aceitam pares de chave-valor arbitrários. Assim, você pode anexar dimensões personalizadas sem modificar o esquema principal. Exemplos comuns incluem order_status_url, gift_wrapped, loyalty_points_earned ou warehouse_id. Essas propriedades ficam disponíveis na personalização com Liquid, nas exportações do Currents e na segmentação por meio de extensões de segmento.

Importante

Os eventos recomendados usam um esquema rigoroso. Por isso, adicionar propriedades personalizadas no nível superior de properties fará com que a validação falhe. Coloque todas as propriedades personalizadas dentro do objeto metadata no nível do evento ou do objeto metadata no nível do produto, dentro de products[]. Elas continuam disponíveis para Liquid, Currents e segmentação, assim como os campos de nível superior.

Validação de eventos e solução de problemas

Quando você envia um evento recomendado de eCommerce por meio de /users/track ou de qualquer SDK da Braze, a Braze valida a carga útil em relação ao esquema JSON do evento durante o processamento do evento recomendado. A validação é executada automaticamente em todo evento cujo nome corresponda exatamente a um evento recomendado (por exemplo, ecommerce.order_placed ou ecommerce.cart_updated).

O que validamos

Para cada evento cujo nome corresponda a um evento recomendado de eCommerce, a Braze verifica:

Por que validamos

Os eventos de eCommerce alimentam recursos que dependem de dados consistentes e previsíveis, incluindo rastreamento de receita, a Liquid tag {% shopping_cart %}, o gatilho de carrinho abandonado e os relatórios. Quando as cargas úteis divergem do esquema, esses recursos produzem imprecisões silenciosas (totais de receita errados, carrinhos ausentes, gatilhos quebrados). A validação garante o contrato logo de início, para que os recursos posteriores se comportem de forma previsível.

Quando a validação é bem-sucedida

O evento é processado como um evento recomendado de eCommerce, com todo o pós-processamento associado. Consulte Eventos recomendados de eCommerce para ver a lista completa de comportamentos disparados por cada tipo de evento.

Verificar um evento bem-sucedido

Depois de enviar um evento, você pode confirmar que ele foi aceito e processado corretamente usando qualquer uma das opções a seguir:

• Registro de usuários de eventos: Abra o perfil do usuário no dashboard e revise a atividade dele. Os eventos recomendados aparecem com a carga útil completa de propriedades, então você pode confirmar que o evento chegou e que os valores correspondem ao que você enviou.
• Relatório de eventos personalizados: Acesse Analytics > Relatório de eventos personalizados para ver as contagens agregadas de cada evento recomendado ao longo do tempo. Isso é útil para confirmar que o tráfego de produção está fluindo como esperado quando sua integração estiver ativa.
• Usuários teste: Marque um usuário no seu espaço de trabalho de desenvolvimento como usuário teste e, depois, dispare eventos da sua integração para esse usuário. Os usuários teste são sinalizados no dashboard, o que facilita isolar e inspecionar o comportamento de ponta a ponta.

Quando a validação falha

O evento não é processado como um evento recomendado. Especificamente:

• O evento é descartado por completo. Eventos recomendados de eCommerce inválidos não chegam ao perfil do usuário, não aparecem no Currents e não ficam disponíveis para segmentação.
• Os recursos posteriores de eventos recomendados não são executados, incluindo:
  • Rastreamento de receita (relatórios de receita, campos calculados do usuário como total_revenue)
  • Atualizações do objeto de carrinho no perfil do usuário
  • Gatilhos Update Cart ou Place Order em Canvas e Campaigns

A forma como os erros são informados depende do caminho de ingestão:

• REST API (/users/track): Cada evento inválido é informado no array errors da resposta. Cada entrada indica qual evento falhou (index) e por quê (type). O campo message de nível superior ainda informa “success”, o que significa apenas que sua solicitação chegou à Braze, e não que todos os eventos eram válidos. Sempre verifique se há um array errors na resposta.
• SDKs da Braze: As chamadas do SDK retornam imediatamente e a validação é executada em segundo plano, então os erros não são enviados de volta ao seu app. Para saber sobre falhas de validação de eventos de eCommerce, fique de olho no e-mail de resumo de falhas (consulte Encontrar falhas).

Exemplo de resposta de erro da API

O endpoint /users/track retorna erros no nível do campo, indicando quais propriedades falharam e por quê. Observe que o message de nível superior pode retornar "success" porque o evento foi aceito no pipeline; o array errors informa quais campos falharam na validação do esquema. Veja a seguir um exemplo de resposta de erro.

1
2
3
4

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

As falhas também são classificadas internamente e agregadas para o e-mail de resumo de falhas:

Nota

Nomes de eventos que não correspondem exatamente a um evento recomendado (por exemplo, ecommerce.OrderPlaced) ignoram totalmente a validação e são registrados como eventos personalizados comuns. Eles aparecem no Currents e na segmentação com o nome que você enviou, mas não recebem nenhum processamento de evento recomendado nem uma entrada em errors na resposta.

Encontrar falhas

A Braze envia aos administradores do seu espaço de trabalho um e-mail com o resumo das falhas de validação de eventos recomendados, para que você possa identificar e corrigir problemas de integração sem monitorar cada evento manualmente.

O e-mail de resumo inclui:

• Contagem total de erros: Contagens de erros do período do relatório.
• Erros por evento: Um detalhamento de quantos eventos falharam para cada tipo de evento recomendado (por exemplo, ecommerce.cart_updated e ecommerce.order_placed). Use isso para identificar quais eventos da sua integração precisam de atenção primeiro.
• Erros por origem: Uma divisão entre API e SDK, para que você possa identificar qual integração está gerando as falhas.

Se você não estiver recebendo esses e-mails ou quiser verificar a lista de destinatários, entre em contato com a equipe da sua conta Braze.

Diagnosticar e corrigir falhas

Quando você receber um e-mail de resumo de falhas:

1. Identifique o evento e a origem com falha. O e-mail separa as falhas por nome do evento e origem da integração (sdk versus rest_api), para que você possa identificar qual integração precisa de correção. Se você tiver várias origens enviando o mesmo evento (por exemplo, o SDK da sua loja e um webhook de backend enviando cart_updated), trate cada uma de forma independente.
2. Compare sua carga útil com o esquema em Esquemas de eventos. A maioria das falhas se encaixa em um destes três padrões:
   • missing_property: Um campo obrigatório está ausente. Para resolver, adicione o campo obrigatório.
   • extra_property: Um campo personalizado está no nível superior de properties. Para resolver, mova o campo personalizado para dentro de metadata (no nível do evento) ou de products[].metadata (por produto).
   • unexpected_data_type: Um valor tem o tipo errado (por exemplo, total_value enviado como string). Para resolver, converta o valor antes de enviar.
3. Teste a carga útil corrigida em um espaço de trabalho de desenvolvimento antes de implementá-la em produção. Envie um evento de teste conhecido para um usuário teste e, depois, verifique o comportamento esperado do evento recomendado no perfil desse usuário (por exemplo, se o objeto de carrinho é atualizado, se a receita aumenta ou se o gatilho de carrinho abandonado é disparado).
4. Monitore o próximo e-mail de falhas para confirmar que a contagem de falhas desse evento, origem e tipo caiu para zero.

Para ver os requisitos completos de propriedades por evento, consulte Esquemas de eventos.