Skip to content

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.

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; relatórios de eCommerce; e campos calculados no perfil do usuário para Receita Total, Total de Pedidos e Total de Reembolsos. Você também pode criar segmentos usando filtragem de propriedades de produto aninhadas por meio de Extensões de segmento, personalizar mensagens de carrinho abandonado com a tag Liquid {% shopping_cart %}, e alimentar recursos do BrazeAITM como Predictive Events, Predictive Churn e recomendações de itens, entre outros recursos.

Como esses eventos seguem um esquema definido, cada recurso compatível pode ler os dados estruturados sem mapeamento personalizado de propriedades ou configuração por recurso da sua parte.

Como os eventos de eCommerce funcionam

Os eventos de eCommerce são eventos personalizados com nomes e esquemas de propriedades predefinidos. Você os envia usando o SDK da Braze ou o endpoint REST API /users/track, e a Braze valida cada evento em relação ao seu esquema na ingestão. Quando a validação é aprovada, a Braze aplica automaticamente o pós-processamento específico para aquele tipo de evento, como calcular campos de receita e gerenciar o estado do carrinho nos perfis de usuário.

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

  • Ações de gatilho “Realiza pedido” em Campaigns, Canvas, 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 (Receita Total, Total de Pedidos, Total de Reembolsos)
  • Gerenciamento de estado do carrinho para fluxos de carrinho abandonado
  • Dados mais ricos para recursos do BrazeAITM como Predictive Events, Predictive Churn e recomendações de itens

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

Nomenclatura de eventos

Os nomes dos eventos são exatos, sensíveis a maiúsculas e minúsculas, e delimitados por ponto. 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 ocorre.

Você não pode personalizar ou renomear eventos.

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

Esquemas de eventos

Os seis eventos recomendados de eCommerce mapeiam as etapas da jornada de compra. Dispare cada evento no momento em que o usuário conclui a ação correspondente.

Diagrama da jornada do usuário através dos seis eventos recomendados de eCommerce: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled e order_refunded.

Dispare quando um usuário visualiza uma página de detalhes do produto. Este evento é compatível com as notificações de volta ao estoque e notificações de queda de preço do catálogo da Braze.

Propriedades do evento

Nome da propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador único 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 para 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 of strings Não Obrigató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"
metadata Object Não Pares chave-valor flexíveis. Sub-propriedade reconhecida: sku (String)

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"],
        "metadata": {
          "sku": "UB-BLK-11-SKU",
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

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

Você pode enviar este evento de duas formas:

  • 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). Você deve 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. Para add, a Braze aumenta a quantidade do item ou adiciona um novo item. Para remove, a Braze diminui a quantidade do item e remove o item quando a quantidade chega a 0. total_value é opcional para add e remove.

Para disparar mensagens a partir deste evento, use o gatilho Perform Cart Updated Event em Canvas e Campaigns. Este gatilho inclui tratamento especial para impedir que o carrinho avance pelo funil de compras.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
cart_id String Sim Identificador único do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinhos do usuário.
action String Não add (incrementa a quantidade ou adiciona um item), remove (decrementa a quantidade; o item é removido quando chega a 0) ou replace (substituição completa do carrinho, mesmo que omitir action).
total_value Float Condicional Obrigatória quando action é omitido ou replace. Opcional quando action é add ou remove.
subtotal_value Float Não Valor do subtotal do carrinho (pós-desconto, pré-imposto/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. Para substituição completa (sem action ou replace), inclua o carrinho completo com quantidades absolutas. Para add ou remove, inclua apenas os itens alterados; 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ória Descrição
product_id String Sim Identificador único 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 substituição completa (sem action ou replace), unidades no carrinho para este item. 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).

Exemplos de código

Cada aba de plataforma abaixo usa o layout de snippet correspondente àquele caminho de integração (por exemplo, cabeçalhos ou rótulos dentro de um bloco de código). As cargas úteis de add, remove e replace são as mesmas em todas as plataformas; apenas a superfície do SDK ou da API difere.

add

add aumenta a quantidade ou adiciona um novo item. A propriedade quantity indica quantas unidades adicionar.

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

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

remove diminui a quantidade pelo valor em quantity. O item é removido quando a quantidade chega a 0.

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

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

replace (ou omitir action) envia o carrinho completo. total_value é obrigatório.

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

braze.logCustomEvent("ecommerce.cart_updated", {
  cart_id: "cart_abc123",
  action: "replace",
  total_value: 234.96,
  currency: "USD",
  source: "web",
  products: [
    {
      product_id: "SKU-RUN-4821",
      product_name: "Ultraboost Running Shoe",
      variant_id: "UB-BLK-11",
      image_url: "https://cdn.example.com/shoes/ub-blk-11.jpg",
      product_url: "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
      quantity: 1,
      price: 189.99,
    },
    {
      product_id: "SKU-SOC-1102",
      product_name: "Performance Running Socks",
      variant_id: "SOC-WHT-L",
      image_url: "https://cdn.example.com/socks/soc-wht-l.jpg",
      product_url: "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
      quantity: 2,
      price: 14.99,
    },
  ],
});
Adicionar

add aumenta a quantidade ou adiciona um novo item. A propriedade quantity indica quantas unidades adicionar.

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

Kotlin

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

JavaScript

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

remove diminui a quantidade pelo valor em quantity. O item é removido quando a quantidade chega a 0.

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

Kotlin

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

JavaScript

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

replace (ou omitir action) envia o carrinho completo. total_value é obrigatório.

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

Kotlin

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

JavaScript

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

add aumenta a quantidade ou adiciona um novo item. A propriedade quantity indica quantas unidades adicionar.

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

Swift

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

Objective-C

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

remove diminui a quantidade pelo valor em quantity. O item é removido quando a quantidade chega a 0.

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

Swift

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

Objective-C

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

replace (ou omitir action) envia o carrinho completo. total_value é obrigatório.

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

Swift

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

Objective-C

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

add aumenta a quantidade ou adiciona um novo item. A propriedade quantity indica quantas unidades adicionar.

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

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

remove diminui a quantidade pelo valor em quantity. O item é removido quando a quantidade chega a 0.

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

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

replace (ou omitir action) envia o carrinho completo. total_value é obrigatório.

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

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

Dispare quando o usuário inicia o fluxo de checkout (por exemplo, seleciona “Checkout” ou acessa a página de checkout).

Propriedades do evento

Propriedade Tipo Obrigatória Descrição
checkout_id String Sim Identificador único 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 carrinhos do usuário.
total_value Float Sim Valor monetário total do checkout.
subtotal_value Float Não Valor do subtotal (pós-desconto, pré-imposto/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 sendo processados no checkout. Consulte a sub-tabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Sub-propriedade reconhecida: checkout_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador único 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 é concluído com sucesso ou o pagamento é confirmado.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
order_id String Sim Identificador único do pedido.
cart_id String Não Identificador do carrinho. Compartilhado entre eventos de carrinho, checkout e pedido para o mapeamento de carrinhos do usuário.
total_value Float Sim Valor monetário total do pedido.
subtotal_value Float Não Valor do subtotal (pós-desconto, pré-imposto/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 de descontos aplicados ao pedido.
discounts Array Não Lista detalhada de descontos aplicados.
products Array Sim Itens do pedido. Consulte a sub-tabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Sub-propriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador único 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 é cancelado.

Propriedades do evento

Propriedade Tipo Obrigatória Descrição
order_id String Sim Identificador único do pedido.
total_value Float Sim Valor monetário total do pedido sendo cancelado. Deve ser ≥ 0 — envie o valor absoluto; a Braze cuida do decremento.
subtotal_value Float Não Valor do subtotal (pós-desconto, pré-imposto/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 de descontos aplicados ao pedido.
discounts Array Não Lista detalhada de descontos aplicados.
cancel_reason String Sim Motivo do cancelamento do pedido.
products Array Sim Itens do pedido cancelado. Consulte a sub-tabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Sub-propriedade reconhecida: order_status_url (String)

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador único 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 é emitido.

Propriedades do evento

Propriedade Tipo de dados Obrigatória Descrição
order_id String Sim Identificador único 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 de descontos originalmente aplicados.
discounts Array Não Lista detalhada de descontos.
products Array Sim Itens sendo reembolsados. Consulte a sub-tabela de propriedades do produto.
source String Sim Origem do evento.
metadata Object Não Pares chave-valor flexíveis. Sub-propriedade reconhecida: order_status_url (String).

Propriedades do produto (products[])

Propriedade Tipo de dados Obrigatória Descrição
product_id String Sim Identificador único 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

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.

Evento O que a Braze faz automaticamente
ecommerce.order_placed Incrementa Receita Total pelo valor de total_value e Total de Pedidos em 1 no perfil do usuário.
ecommerce.order_cancelled Decrementa Total de Pedidos em 1.
ecommerce.order_refunded Decrementa Receita Total pelo valor de total_value e incrementa Valor Total de Reembolsos.
ecommerce.cart_updated Cria ou atualiza o objeto de mapeamento de carrinhos no perfil do usuário (cargas úteis de carrinho completo ou atualizações incrementais com action opcional: add, remove ou replace). O carrinho expira após 30 dias sem atualização.
ecommerce.product_viewed Nenhuma alteração no perfil do usuário. Disponível para segmentação, disparo e recursos do BrazeAITM (como recomendações de itens).
ecommerce.checkout_started Nenhuma alteração no perfil do usuário. Disponível para segmentação e disparo (por exemplo, fluxos de checkout abandonado).

Implementar eventos de eCommerce

Você pode enviar eventos de eCommerce pelo endpoint /users/track (server-side) ou pelo método do SDK do cliente logCustomEvent.

Enviar eventos server-side

Use o endpoint /users/track para enviar eventos de eCommerce do seu backend. Cada evento requer o nome exato do evento, o external_id do usuário e um objeto de propriedades correspondente ao esquema do evento.

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

POST /users/track

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

Pontos de dados e cobrança

Os eventos de eCommerce não consomem pontos de dados. Você pode registrá-los sem nenhum impacto no seu consumo 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 disparadas de Campaigns 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 boa prática, envie apenas as informações de produto necessárias para disparar, personalizar ou atribuir o evento. Armazene detalhes mais ricos do produto — como descrições, listas completas de variantes, estoque ou imagens alternativas — nos Catálogos da Braze. Referencie esses detalhes por product_id ou variant_id ao enviar mensagens. Use o objeto metadata seletivamente para contexto específico do pedido ou produto que o envio de mensagens utilizará.

Tratamento de moeda

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

Campo source

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

Flexibilidade de metadata

Tanto o objeto metadata no nível do evento quanto no nível do produto aceitam pares chave-valor arbitrários, permitindo que você anexe dimensões personalizadas sem modificar o esquema principal. Exemplos comuns incluem order_status_url, gift_wrapped, loyalty_points_earned ou warehouse_id. Essas propriedades estão disponíveis na personalização com Liquid, exportações do Currents e segmentação por meio de Extensões de segmento.

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 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 é validado

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

Verificação Exemplo
Nome do evento Deve ser exato. Por exemplo, ecommerce.cart_updated está correto — não ecommerce.Cart_Updated, cartupdated ou cart_updated.
Propriedades obrigatórias presentes order_placed requer order_id, total_value, currency, products e source.
Tipos de dados corretos total_value deve ser um número; currency deve ser uma string; products deve ser um array.
Sem propriedades extras no nível superior Campos personalizados em properties causam falha. Use o objeto metadata em vez disso.
Restrições de valor Campos monetários devem ser ≥ 0. currency deve ser uma string ISO 4217 válida.
Campos por produto Cada item em products[] deve incluir product_id, product_name, variant_id, quantity e price.

Por que validamos

Os eventos de eCommerce alimentam recursos que dependem de dados consistentes e previsíveis, incluindo rastreamento de receita, a tag Liquid {% shopping_cart %}, o gatilho de carrinho abandonado e relatórios. Quando as cargas úteis divergem do esquema, esses recursos produzem imprecisões silenciosas (totais de receita incorretos, carrinhos ausentes, gatilhos quebrados). A validação impõe o contrato antecipadamente para que os recursos downstream se comportem 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 Esquemas de eventos para a lista completa de comportamentos disparados por cada tipo de evento.

Verificar um evento bem-sucedido

Após enviar um evento, você pode confirmar que ele foi aceito e processado corretamente usando qualquer um dos seguintes métodos:

  • Registro de usuários de eventos: abra o perfil do usuário no dashboard e revise a atividade. Os eventos recomendados aparecem com a carga útil completa de propriedades, para que você possa confirmar que o evento chegou e os valores correspondem ao que foi enviado.
  • Relatório de eventos personalizados: acesse Analytics > Custom Events para ver contagens agregadas de cada evento recomendado ao longo do tempo. Isso é útil para confirmar que o tráfego de produção está fluindo conforme esperado quando sua integração está 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 são sinalizados no dashboard, facilitando o isolamento e a inspeção do comportamento de ponta a ponta.

Quando a validação falha

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

  • O evento é descartado completamente. Eventos recomendados de eCommerce inválidos não são registrados no perfil do usuário, não aparecem no Currents e não ficam disponíveis para segmentação.
  • Os recursos downstream 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 “Perform Cart Updated Event” ou “Placed Order” em Canvas e Campaigns

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

  • REST API (/users/track): cada evento inválido é reportado no array de erros da resposta. Cada entrada informa qual evento falhou (índice) e por quê (tipo). O campo message de nível superior ainda diz “success”, o que significa apenas que sua requisiçã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ê. Note 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 de esquema. Veja o exemplo de resposta de erro a seguir.

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:

Tipo de falha Significado Exemplo
missing_property Um campo obrigatório está ausente. order_placed enviado sem order_id.
extra_property Um campo foi adicionado que o esquema não define. Um campo personalizado gift_wrapped no topo de properties em vez de dentro de metadata.
unexpected_data_type Um campo está com o tipo errado. total_value: "29.99" (string) em vez de 29.99 (número).

Encontrar falhas

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

O e-mail de resumo inclui:

  • Contagem total de erros: contagens de erros para o período de relatório.
  • Erros por evento: uma divisão 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 na 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 está recebendo esses e-mails ou deseja 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 de evento e origem da integração (sdk versus rest_api), para que você possa identificar qual integração precisa da correção. Se você tem múltiplas origens enviando o mesmo evento (por exemplo, o SDK da sua loja e um webhook de backend ambos enviando cart_updated), trate-os independentemente.
  2. Compare sua carga útil com o esquema em Esquemas de eventos. A maioria das falhas se enquadra em um dos 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 está com 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 implantar 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, o objeto de carrinho é atualizado, a receita é incrementada ou o gatilho de carrinho abandonado é disparado).
  4. Monitore o próximo e-mail de falhas para confirmar que a contagem de falhas para aquele evento, origem e tipo caiu para zero.

Para os requisitos completos de propriedades por evento, consulte Esquemas de eventos.
New Stuff!