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 com sucesso, 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, além de 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 por propriedades de produto aninhadas usando extensões de segmento e personalizar mensagens de carrinho abandonado com a Liquid tag {% shopping_cart %}. Os eventos também alimentam recursos da 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 mapeamento de propriedades personalizadas nem configuração específica por recurso da sua parte.

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 ou a Ingestão de dados na nuvem (CDI). A Braze valida cada evento em relação ao seu esquema no momento da 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 de campos de receita e o gerenciamento do estado do carrinho nos perfis de usuário.

Nota

Uploads de CSV não são compatíveis com eventos de eCommerce. Use o SDK, /users/track ou CDI para enviar esses eventos.

Os eventos de eCommerce funcionam em todos os lugares onde outros eventos personalizados funcionam: gatilhos e filtros de eventos personalizados realizados, relatórios de eventos personalizados e muito mais. No entanto, a validação de esquema desses eventos 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 ricos para recursos da 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 onde a plataforma 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 delimitados 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 o 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. Já ecommerce.order_cancelled e ecommerce.order_refunded usam logCustomEvent.

Os eventos de reembolso e cancelamento normalmente são enviados pelo seu servidor por meio da REST API da Braze, porque costumam depender da conclusão de uma lógica no lado do servidor, como o seu fluxo de reembolso. Para 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 uma página de detalhes do 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 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 de queda de preço. Valores aceitos: "price_drop", "back_in_stock"
metadata	Objeto	Não	Pares de chave-valor flexíveis (por exemplo, category ou brand).

Exemplo da 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

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

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 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 maneiras:

• Substituição completa do carrinho: Omita action ou defina action como replace. Inclua o conjunto completo de itens 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 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 do item ou adiciona um novo item. Com remove, a Braze diminui a quantidade do item e o remove quando a quantidade chega a 0. total_value é opcional para add e remove.

Aviso

Para um mesmo carrinho, use atualizações incrementais (add ou remove) ou a substituição completa (sem action ou com replace). 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 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 pelo funil de compras.

Dica

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. Se dois perfis de usuário forem mesclados, a Braze preserva os dois carrinhos.

Propriedades do evento

Propriedade	Tipo de dados	Obrigatório	Descrição
cart_id	String	Sim	Identificador exclusivo do carrinho. Compartilhado entre os eventos de carrinho, checkout e pedido para o mapeamento do carrinho do usuário.
action	String	Não	add (aumenta a quantidade ou adiciona um item), remove (diminui a quantidade; o item é removido 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. Opcional quando action é add ou remove.
subtotal_value	Float	Não	Valor do subtotal do carrinho (após descontos, antes de impostos/frete).
tax	Float	Não	Total de impostos aplicados ao carrinho.
shipping	Float	Não	Custo total de frete do carrinho.
currency	String	Sim	Código ISO 4217 de três letras.
products	Array	Sim	Itens desta atualização. Na substituição completa (sem action ou com replace), inclua o carrinho completo com quantidades absolutas. Com add ou remove, inclua apenas os itens alterados; consulte as propriedades do produto.
source	String	Sim	Origem do evento.
metadata	Objeto	Não	Pares de 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	Inteiro	Sim	Na substituição completa (sem action ou com replace), unidades deste item no carrinho. Com add ou remove, quantas unidades adicionar ou remover.
price	Float	Sim	Preço unitário da variante.
metadata	Objeto	Não	Pares de 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 acessar a página de checkout).

Implementação no lado do cliente

Use as APIs de eventos de eCommerce do SDK, quando disponíveis. Para 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 os eventos de carrinho, checkout e pedido para o mapeamento do carrinho do usuário.
total_value	Float	Sim	Valor monetário total do checkout.
subtotal_value	Float	Não	Valor do 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	Objeto	Não	Pares de 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	Inteiro	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Objeto	Não	Pares de chave-valor flexíveis (por exemplo, cor, tamanho).

Exemplo da 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 exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse é o principal evento gerador de receita. Ele incrementa total_revenue pelo valor em total_value e incrementa 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 os eventos de carrinho, checkout e pedido para o mapeamento do carrinho do usuário.
total_value	Float	Sim	Valor monetário total do pedido.
subtotal_value	Float	Não	Valor do 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	Objeto	Não	Pares de 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	Inteiro	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Objeto	Não	Pares de chave-valor flexíveis (por exemplo, color ou size).

Exemplo da 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 exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse evento decrementa 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. Deve ser ≥ 0 — envie o valor absoluto; a Braze cuida do decremento.
subtotal_value	Float	Não	Valor do 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	Objeto	Não	Pares de 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	Inteiro	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Objeto	Não	Pares de chave-valor flexíveis (por exemplo, color ou size).

Exemplo da 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 exemplos de implementação específicos de cada plataforma, consulte Registrar eventos de eCommerce pelo SDK da Braze.

Importante

Esse evento decrementa total_revenue pelo valor em total_value e incrementa 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. Deve ser ≥ 0 — envie o valor absoluto; a Braze cuida do 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	Objeto	Não	Pares de 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	Inteiro	Sim	Número de unidades no carrinho.
price	Float	Sim	Preço unitário da variante.
metadata	Objeto	Não	Pares de chave-valor flexíveis (por exemplo, color ou size).

Exemplos da 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 fixamente como 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 têm um limite de 102.400 bytes (100 KB) por evento. Para mensagens disparadas de Campaign e Canvas, as trigger_properties enviadas para /campaigns/trigger/send e /canvas/trigger/send têm um limite padrão mais restrito 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 por product_id ou variant_id ao enviar mensagens. Use o objeto metadata de forma seletiva, apenas para o contexto específico 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 é informado. Esse valor convertido é o que aparece nas métricas de receita.

Dica

Se você opera apenas em USD, defina "currency": "USD" diretamente 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 veio. 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, tanto no nível do evento quanto no nível do produto, aceitam pares 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 rígido. Por isso, adicionar propriedades personalizadas no nível superior de properties fará a validação falhar. 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 pelo /users/track ou por qualquer SDK da Braze, a Braze valida a carga útil em relação ao esquema JSON do evento durante o processamento. 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 corresponde 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 geram imprecisões silenciosas (totais de receita errados, carrinhos ausentes, gatilhos quebrados). A validação aplica o contrato logo de início, para que os recursos posteriores funcionem de forma previsível.

Quando a validação é aprovada

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 das 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, em seguida, dispare eventos da sua integração para esse usuário. Os usuários teste ficam 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 de 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 de 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 de erros da resposta. Cada entrada indica qual evento falhou (índice) e por quê (tipo). O campo de mensagem de nível superior ainda diz “success”, o que significa apenas que sua solicitação chegou à Braze, não que todos os eventos eram válidos. Sempre verifique se há um array de erros 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 atento ao 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 geram 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 precisar 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 com falha e a origem. O e-mail separa as falhas por nome do evento e origem da integração (sdk ou rest_api), para que você possa identificar qual integração precisa da correção. Se várias origens enviam o mesmo evento (por exemplo, o SDK da sua loja virtual 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 enquadra 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 (nível do evento) ou products[].metadata (por produto).
   • unexpected_data_type: Um valor é do 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 liberar em produção. Envie um evento de teste conhecido para um usuário teste e, em seguida, 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. Acompanhe o próximo e-mail de falhas para confirmar que a contagem de falhas daquele evento, origem e tipo caiu para zero.

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