How to use eCommerce Events

eCommerce recommended events use a shared, order-level schema, which lets Braze build reliable features on top of your eCommerce data—including user profiles, segmentation, messaging, reporting, and AI-powered recommendations. The sections in this article cover how to use each capability in Braze.

See Event schemas for property requirements and data types, and Event validation and troubleshooting for what happens when an event fails validation.

Because eCommerce events follow a predictable schema, Braze can build reliable features on top of them, from revenue tracking and pre-built Canvas templates to AI-powered recommendations. The following sections give you a quick overview of each capability with links to the full documentation.

Commerce tab

The Commerce tab on each user profile combines two modules: Order activity (calculated revenue and order metrics) and Active cart (the latest cart from ecommerce.cart_updated events).

Order activity

The Order activity module surfaces three calculated metrics that update in real time as events are processed. The order-level model of these calculations cleanly separates product prices from total order value.

Metric	Formula
Total Revenue	sum (order_placed.total_value) − sum (order_refunded.total_value)
Total Orders	count (distinct order_placed) − count (distinct order_cancelled)
Total Refund Value	sum (order_refunded.total_value)

Active cart

The Active cart module shows the latest cart on the user profile. That view is especially helpful while you test. You can use it to confirm cart contents, validate cart-based journeys, or verify that ecommerce.cart_updated events are updating the profile as you expect.

Active cart includes the following:

• Cart ID — Identifier for the cart that last received an ecommerce.cart_updated event.
• Last updated — Timestamp of the most recent cart update.
• Total cart value — Total value of the line items in the current cart.
• View products — A link to open the list of products in the cart (up to 50 products).

eCommerce orchestration

Segmentation

Braze provides three ways to segment users based on eCommerce data:

• eCommerce filters: Use the eCommerce category in the segmenter, which contains filters powered by eCommerce recommended events (such as Last Order Placed, Total Revenue, and Average Order Value). For a complete list of available filters, see Segment filters.
• Custom event filters: Because eCommerce events behave like custom events, all existing custom event filters work immediately. For example, you can filter by “Has performed custom event ecommerce.order_placed more than X times” or “First performed custom event ecommerce.order_placed”.
• Segment Extensions: For segmenting off nested event properties including the nested products array or the metadata objects properties, use Segment Extensions with nested event property filtering. This lets you build audiences like “users who purchased product SKU-123 in the last 90 days” or combine criteria across different properties of the same order.

If you need to filter on custom properties that aren’t part of the documented event schema, nest them under metadata when you log the event (for example, metadata.color instead of color). Custom top-level properties you send through the API or SDK aren’t valid for extension property filters—even if those properties appear in your event data. Using a non-allowlisted top-level property prevents the extension from saving or unarchiving.

Triggering

You can use performed custom event triggers with eCommerce events throughout Braze, just like with other custom events. For abandoned cart flows, use the Update Cart trigger to properly capture cart updates.

Additionally, Braze offers a dedicated Place Order trigger, which lets you start journeys or take actions when a user places an order. For more information, see Action-based delivery.

Property filters

Place Order and Update Cart triggers can also filter on the properties carried by the event, so a trigger fires only for the orders or carts you care about:

• Basic properties match a top-level property on the event, such as total_value or currency.
• Nested properties look inside the products array. Because each product carries its own properties, products[].metadata.category matches when any product in the order or cart satisfies the condition.

Nest custom product fields under metadata (for example, products[].metadata.brand). A product property that isn’t part of the event schema fails validation, so a filter on it never matches.

For example, combining total_value is more than 1000 with products[].metadata.category equals shoes triggers only for high-value orders that contain footwear. Before property filters, you could trigger on an order being placed but not on what the order contained.

Property filters are available on the following surfaces:

• Place Order: Campaign and Canvas triggers, exception events, Canvas exit criteria, action paths, conversion events, and Content Card removal events. Basic and nested properties are supported.
• Update Cart: Campaign and Canvas triggers, exception events, Canvas exit criteria, and action paths. Basic and nested properties are supported. On conversion events, Content Card removal events, and in-app message triggers, Update Cart is backed by the ecommerce.cart_updated custom event and supports basic properties only.

Nested properties aren’t supported on in-app message triggers, which are evaluated on the device.

Scoping an order to a specific product

To trigger only when an order contains a specific product, add a nested property filter on the Place Order trigger:

Goal	Nested property filter
Product name	products[].product_name equals value
Product ID	products[].product_id equals value
Product variant ID	products[].variant_id equals value

Saved behaviors with product scope

If you configured a Place Order behavior before property filters were available, it may still use Place order for specific product with a Product Identifier (product name, product_id, or variant_id). Those saved behaviors keep working and continue to match exactly as before, so existing campaigns and Canvases are unaffected.

To switch a saved behavior to property filters, select Place any order. That replaces the product scope controls with property filters. Use the following table to recreate the same scope:

Previous Product Identifier	Equivalent nested property filter
Product name	products[].product_name equals value
Product ID	products[].product_id equals value
Product variant ID	products[].variant_id equals value

Liquid personalization

eCommerce events support Liquid personalization the same way custom events do; you can reference event properties directly in your messaging. To pull product images, pricing, or other catalog data into your messages, join your catalog with the event using product_id or variant_id as the linking identifier. The {% shopping_cart %} Liquid tag lets you loop through a user’s current cart contents for abandoned cart reminders, checkout nudges, or order confirmations. For ready-to-use code samples, see eCommerce use cases.

For a no-code alternative, drag-and-drop product blocks are available in the early access program.

eCommerce Canvas templates

Braze provides ready-to-use Canvas templates pre-configured with eCommerce recommended events as entry, exit, and conversion criteria, so you can launch lifecycle flows without custom setup. Each template ships with drag-and-drop email designs and supports drag-and-drop product blocks (currently in early access). For detailed use cases and Liquid examples, see eCommerce use cases.

These templates cover the most common eCommerce lifecycle flows. Use them as a starting point, then customize the timing, channels, and creative for your audience.

• abandoned browse
• abandoned cart
• abandoned checkout
• order confirmation and survey

Customize templates

These templates are designed to be a starting point. Common customizations include:

• Customize the email: Each template includes a pre-configured email built with the drag-and-drop editor which is fully editable to match your brand and content.
• Add channels: Pair email with push, SMS, or in-app messages for cross-channel reinforcement.
• Add delays and decision splits: Branch users by behavior (for example, high-value cart compared to low-value cart) or wait periods between messages.
• Swap creative: Replace the included email template with your brand’s visual style.
• Use product blocks: Use drag-and-drop product blocks (in the early access program) to dynamically render abandoned cart contents or browsed products without writing custom Liquid.

For more advanced lifecycle strategies, including Liquid personalization examples, see eCommerce use cases.

eCommerce reporting

eCommerce recommended events power the same revenue surfaces customers already use today. When your integration is sending eCommerce events, the following reports include eCommerce revenue automatically:

Report	What it shows
Revenue Report	Total revenue, average daily revenue, daily purchases, and revenue per user over time across all sources for your selected date range and apps.
Last Touch Attribution Revenue dashboard	Revenue attributed to the last campaign or Canvas a user interacted with before placing an order. Touch events include email clicks, push opens, Content Card clicks, in-app message clicks, and SMS or WhatsApp short link clicks.
Campaign and Canvas analytics	Total revenue attributed to a specific campaign or Canvas within the primary conversion window.
Conversions report	Revenue tied to conversion events on campaigns and Canvases. Note: To count ecommerce.order_placed revenue, the campaign or Canvas must use the Places Order conversion event type.
Segment Insights	Revenue comparisons across segments in the segment insights dashboard.
Report Builder	Revenue metrics in custom reports built in Report Builder.
Dashboard Builder	Revenue metrics in custom dashboards built in Dashboard Builder.

For non-user calculated fields (for example, campaign or Canvas revenue), revenue is calculated the same way across all reports: price multiplied by quantity per product in the order, summed across the products in each order_placed event.

BrazeAI^TM

Predictive Events, Predictive Churn, and item recommendations support eCommerce events as target events and signals, and have a dedicated “Order Placed” option. The standardized schema makes these models more reliable because the data is consistent across your user base.

Export data

Braze offers several ways to export eCommerce event data for use in your data warehouse, BI tools, or downstream systems. eCommerce recommended events are exported through the same channels as your other event data.

Export path	What’s included
Currents	eCommerce events stream as custom events; search the ecommerce.* namespace to find them. Products from each order are available as purchases.
Snowflake Data Sharing	eCommerce events are shared as custom events; search the ecommerce.* namespace to find them. Products from each order are available in the purchases table.
Export segment data to CSV	CSV export of segment members. To include eCommerce events, select them by name from the custom events dropdown.
Export user profile by Segment (API)	User profile data for segment members, returned via API. eCommerce events are included as custom events.

How do I segment users by a specific product?

The segmenter allows you to filter by the number of times a user performed an eCommerce event. To filter by specific product properties (such as product_id or product_name), use Segment Extensions, which support nested event property filtering. For example, you can find all users who purchased product “SKU-123” in the last 90 days.