Braze Recommended Ecommerce Events Beta

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.

Field mappings

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

Fields marked Required are required by Braze for commerce handling. Missing values do not block delivery. 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).

Cart Updated

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

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.

Order Placed

Maps from Order Completed.

Each discounts[] item is passed through with the shape { code, amount, type }.

Order Refunded

Maps from Order Refunded.

Order Cancelled

Maps from Order Cancelled.

Product properties

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

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).

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:

{
  "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.

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:

{
  "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

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 the integration logs a 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

Missing Braze-required fields never fail or drop an event. Braze accepts the payload and processes it as a plain custom event instead of a commerce event, so the integration sends it with the field absent.

The same send-anyway behavior applies to type mismatches — values that cannot be coerced without loss are sent as-is with a warning.

The Event details table lists the warning category, status code, sample response, and sample payload:

See more

• Braze Destination Setup Guide
• Braze Cloud Mode Integration
• Braze Device Mode Integration
• Ecommerce Events Specification
• Braze recommended events