Braze Recommended Ecommerce Events

Beta
Complete Braze recommended ecommerce events reference for event mappings, required properties, and validation behavior.

Braze recommended ecommerce events are currently in beta.

When Enable ecommerce recommended events connection setting is toggled on, the Braze destination maps supported RudderStack ecommerce track events to Braze recommended ecommerce events (ecommerce.*).

Note that:

  • The Enable ecommerce recommended events setting is toggled on by default for all new destinations.
  • The mapping is the same in cloud mode and device mode.
  • In hybrid mode, user-generated track events are sent through cloud mode, so the same mapping applies.
  • To use the legacy Order Completed purchase mapping instead, toggle Enable ecommerce recommended events off in the event settings.

When the setting is toggled on, Order Completed is sent as one ecommerce.order_placed custom event per order instead of Braze purchases.

Rebuild Braze purchase and revenue analytics and Made Purchase segments against ecommerce.order_placed.

Event mappings

Event names are matched after trimming whitespace, without regard to case. For example, order completed and Order Completed both map.

RudderStack eventBraze eventaction
Product Viewedecommerce.product_viewed—
Product Addedecommerce.cart_updatedadd
Product Removedecommerce.cart_updatedremove
Checkout Startedecommerce.checkout_started—
Order Completedecommerce.order_placed—
Order Refundedecommerce.order_refunded—
Order Cancelledecommerce.order_cancelled—

Field mappings

Where a Braze field lists more than one RudderStack property, the integration uses the first present value.

Note that:

  • Fields marked Required are required by Braze for commerce handling.
  • Missing values do not prevent RudderStack from sending the event — Braze usually accepts it and processes it as a plain custom event.
  • In cloud mode, an event that Braze rejects is discarded — see Missing required fields.

Product Viewed

Maps from Product Viewed. Product fields are read from the top-level event properties (this event has no products array).

Braze fieldRudderStack property
product_id
Required
product_id
sku
product_name
Required
name
variant_id
Required
variant
sku
product_id
price
Required
price
currency
Required
currency
image_urlimage_url
product_urlurl
typetype (array)

Cart Updated

Maps from Product Added (action: add) and Product Removed (action: remove).

Braze fieldRudderStack property
cart_id
Required
cart_id
currency
Required
currency
products[]
Required
products[] or top-level product fields folded into one item
total_valuetotal
revenue
value
subtotal_valuesubtotal_value
taxtax
shippingshipping

Note that:

  • Product Added and Product Removed typically send product fields at the top level.
  • The integration folds those fields into a one-item products array — if you send products[] explicitly, that array is used instead.

Checkout Started

Maps from Checkout Started.

Braze fieldRudderStack property
checkout_id
Required
checkout_id
order_id
total_value
Required
total
revenue
value
currency
Required
currency
products[]
Required
products[]
cart_idcart_id
subtotal_valuesubtotal_value
taxtax
shippingshipping

Order Placed

Maps from Order Completed.

Braze fieldRudderStack property
order_id
Required
order_id
total_value
Required
total
revenue
value
currency
Required
currency
products[]
Required
products[]
cart_idcart_id
subtotal_valuesubtotal_value
taxtax
shippingshipping
total_discountsdiscount
total_discounts
discountsdiscounts[]
Each discounts[] item is passed through with the shape { code, amount, type }.

Order Refunded

Maps from Order Refunded.

Braze fieldRudderStack property
order_id
Required
order_id
total_value
Required
total
revenue
value
currency
Required
currency
products[]
Required
products[]
total_discountsdiscount
total_discounts
discountsdiscounts[]

Order Cancelled

Maps from Order Cancelled.

Braze fieldRudderStack property
order_id
Required
order_id
total_value
Required
total
revenue
value
currency
Required
currency
cancel_reason
Required
cancel_reason
reason
products[]
Required
products[]
subtotal_valuesubtotal_value
taxtax
shippingshipping
total_discountsdiscount
total_discounts
discountsdiscounts[]

Product properties

These fields apply to each item in products[] on every mapped event except ecommerce.product_viewed.

Braze fieldRudderStack property
product_id
Required
product_id
sku
product_name
Required
name
variant_id
Required
variant
sku
product_id
quantity
Required
quantity
price
Required
price
image_urlimage_url
product_urlurl
Unmapped product keys are nested under products[].metadata.

Examples

The destination sends a Braze custom event (name and properties). Cloud and device mode wrap it the same way as other custom events.

Product Viewed

Product Viewed maps to ecommerce.product_viewed. Because both product_id and sku are present, product_id wins. variant_id comes from variant. sku is consumed as a fallback key, so it is not copied into metadata. source is set automatically (web for this JavaScript SDK call).

javascript
rudderanalytics.track("Product Viewed", {
  product_id: "622c6f5d5cf86a4c77358033",
  sku: "8472-998-0112",
  name: "Cones of Dunshire",
  variant: "expansion pack",
  price: 49.99,
  currency: "USD",
  url: "https://www.website.com/product/path",
  image_url: "https://www.website.com/product/path.webp"
});

Braze custom event:

json
{
  "name": "ecommerce.product_viewed",
  "properties": {
    "product_id": "622c6f5d5cf86a4c77358033",
    "product_name": "Cones of Dunshire",
    "variant_id": "expansion pack",
    "price": 49.99,
    "currency": "USD",
    "product_url": "https://www.website.com/product/path",
    "image_url": "https://www.website.com/product/path.webp",
    "source": "web"
  }
}

Product Added

Product Added maps to ecommerce.cart_updated with action: add. The top-level product fields are folded into a one-item products array.

javascript
rudderanalytics.track("Product Added", {
  cart_id: "skdjsid2dkdkd",
  product_id: "622c6f5d5cf86a4c77358033",
  name: "Cones of Dunshire",
  variant: "expansion pack",
  price: 49.99,
  quantity: 1,
  currency: "USD"
});

Braze custom event:

json
{
  "name": "ecommerce.cart_updated",
  "properties": {
    "cart_id": "skdjsid2dkdkd",
    "currency": "USD",
    "products": [
      {
        "product_id": "622c6f5d5cf86a4c77358033",
        "product_name": "Cones of Dunshire",
        "variant_id": "expansion pack",
        "quantity": 1,
        "price": 49.99
      }
    ],
    "action": "add",
    "source": "web"
  }
}

Automatic fields

Field
Behavior
sourceSet on every mapped event. If properties.source is web, ios, or android, that value is used. Otherwise, cloud mode derives source from the event channel and OS, and device mode sends the source platform (web, ios, or android).
actionSet to add or remove for ecommerce.cart_updated from the RudderStack event name. A customer-sent properties.action is not used.
metadataUnmapped event-level properties. Unmapped product keys go to products[].metadata. These keys are passed through, not dropped.

Normalization

  • Lossless type coercion: Numeric strings are converted to numbers for float fields ("12.5" becomes 12.5). Integral strings are converted to integers ("2" becomes 2). "2.5" on an integer field stays a string and, in device mode, the SDK logs a type-mismatch warning. Numbers are stringified for string fields. Integers are accepted for float fields. Values that cannot be coerced without loss are sent as-is.
  • Empty-value scrubbing: null, "", {}, and [] are removed from the payload. 0 and false are kept.

Missing required fields

RudderStack sends the event with the Braze-required field absent. A required field sent as null, "", {}, or [] is scrubbed from the payload and treated the same way as a missing field. What happens next depends on the connection mode and on whether Braze accepts or rejects the item — when Braze accepts it, it is processed as a plain custom event instead of a commerce event.

Connection mode
Behavior
Device modeThe SDK logs a warning that lists the missing fields (browser console, Logcat, or Xcode console, depending on the SDK log level).
Cloud modeEvents that Braze rejects are discarded and counted as failed deliveries on the destination Events tab.

In the Event details table, click the event row to see the Braze error and a sample payload.

The same send-anyway behavior applies to type mismatches: values that cannot be coerced without loss are sent as-is. In device mode, the SDK logs a separate warning listing the mismatched fields. In cloud mode, an event that Braze rejects because of a type mismatch is discarded on the same path as a missing field.

See more

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.