STRATCONN-6824 - [Braze] - ecommerce.cart_updated support

[joe-ayoub-segment]

Adding support to Braze destination for Ecommerce ecommerce.cart_updated events.
https://twilio-engineering.atlassian.net/browse/STRATCONN-6824

Also adds new presets for Product Added and Product Removed.

Testing

New unit tests:

• Cart Updated with all fields (action, subtotal_value, tax, shipping, cart_id)
• Cart Updated with minimal fields (just cart_id)
• Cart Updated in the batch test (5th event alongside existing 4)
• Product Viewed with catalog_type: ['price_drop', 'back_in_stock']

Updated unit tests:

• Order Placed — expected JSON now includes subtotal_value, tax, shipping
• Checkout Started — expected JSON now includes subtotal_value, tax, shipping
• Order Cancelled — expected JSON now includes subtotal_value, tax, shipping
• Batch test — all events updated with new fields + cart_updated added
• Both multistatus tests — sent objects and nock bodies updated with new fields

Staging Test Plan

1. Cart Updated (replace) — Send a cart_updated event with action: 'replace', cart_id, total_value,
   subtotal_value, tax, shipping, and products. Verify Braze receives all fields.
2. Cart Updated (add/remove) — Send a cart_updated with action: 'add' and only cart_id + products (no
   subtotal/tax/shipping). Verify optional fields are omitted cleanly.
3. Checkout Started with new fields — Send checkout_started with subtotal_value, tax, shipping
   populated. Verify they appear in Braze payload.
4. Product Viewed with catalog_type — Send product_viewed with catalog_type: ['price_drop',
   'back_in_stock']. Verify Braze receives type: ["price_drop", "back_in_stock"] in properties.
5. Order Placed (batch) — Send a batch with mixed event types including cart_updated. Verify all
   events process correctly in a single request.

Security Review

Please ensure sensitive data is properly protected in your integration.

• Reviewed all field definitions for sensitive data (API keys, tokens, passwords, client secrets) and confirmed they use type: 'password'

New Destination Checklist

• Extracted all action API versions to verioning-info.ts file. example

[Copilot]

Pull request overview

This PR attempts to add Braze ecommerce support for an additional event type by introducing ecommerce.cart_updated alongside existing multi-product ecommerce recommended events.

Changes:

• Enabled the CART_UPDATED event name constant and added it into the ecommerce event unions/types.
• Added CART_UPDATED handling in the ecommerce JSON builder (getJSONItem) to emit a Cart Updated event payload.
• Expanded several ecommerce event TypeScript interfaces with additional optional pricing fields (e.g., subtotal_value, tax, shipping).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
packages/destination-actions/src/destinations/braze/ecommerce/types.ts	Adds CartUpdatedEvent and extends ecommerce event typings/unions.
packages/destination-actions/src/destinations/braze/ecommerce/functions.ts	Adds runtime JSON-building support for EVENT_NAMES.CART_UPDATED.
packages/destination-actions/src/destinations/braze/ecommerce/constants.ts	Enables CART_UPDATED in the Braze ecommerce event name constants.

Comments suppressed due to low confidence (2)

packages/destination-actions/src/destinations/braze/ecommerce/constants.ts:6

• CART_UPDATED is now defined/handled in code, but the ecommerce action’s field definitions still have the “Cart Updated” choice and related depends_on / required conditions commented out (see packages/destination-actions/src/destinations/braze/ecommerce/fields.ts). As-is, users likely can’t select/configure this event through the action schema, so the added support won’t be reachable. Please enable the choice and any required/depends_on rules and regenerate the action types as needed.

  PRODUCT_VIEWED: 'ecommerce.product_viewed',
  CHECKOUT_STARTED: 'ecommerce.checkout_started',
  CART_UPDATED: 'ecommerce.cart_updated',
  ORDER_PLACED: 'ecommerce.order_placed',
  ORDER_CANCELLED: 'ecommerce.order_cancelled',

packages/destination-actions/src/destinations/braze/ecommerce/types.ts:92

• CartUpdatedEvent.properties.cart_id is typed as required, but the action Payload defines cart_id as optional and the field description suggests Braze can default it when omitted. Consider making cart_id optional in CartUpdatedEvent (and/or conditionally including it in the JSON properties object) to keep the TypeScript types aligned with the actual payload behavior.

export interface CartUpdatedEvent extends MultiProductBaseEvent {
    name: CartUpdatedEventName
    properties: MultiProductBaseEvent['properties'] & {
        cart_id: string
        action?: 'add' | 'remove' | 'replace'

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:208

• In the CART_UPDATED branch, cart_id is always added to properties via a type assertion (cart_id: cart_id as string). If the input omits cart_id (currently allowed by the field schema), the outbound payload will include cart_id: undefined, which is likely to be rejected by Braze or cause inconsistent behavior. Prefer conditionally adding cart_id only when present, or enforce cart_id as required for this event.

        case EVENT_NAMES.CART_UPDATED: {
          const { cart_id, action, subtotal_value, tax, shipping } = payload as Payload

          const event: CartUpdatedEvent = {
            ...multiProductEvent,
            name: EVENT_NAMES.CART_UPDATED,
            properties: {
              ...multiProductEvent.properties,
              cart_id: cart_id as string,
              ...(action ? { action: action as 'add' | 'remove' | 'replace' } : {}),
              ...(typeof subtotal_value === 'number' ? { subtotal_value } : {}),
              ...(typeof tax === 'number' ? { tax } : {}),
              ...(typeof shipping === 'number' ? { shipping } : {})
            }

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:223

• cart_id is included for Cart Updated via depends_on only, so it’s optional at validation time. Given the new CART_UPDATED implementation currently assumes a string cart_id, either add a required condition for name = ecommerce.cart_updated (and/or align the runtime to omit it when absent).

const cart_id: InputField = {
    label: 'Cart ID',
    description: 'Unique identifier for the cart. If no value is passed, Braze will determine a default value (shared across cart, checkout, and order events) for the user cart mapping.',
    type: 'string',
    default: {'@path': '$.properties.cart_id'},
    depends_on: {
        match: 'any',
        conditions: [
            {
                fieldKey: 'name',
                operator: 'is',
                value: EVENT_NAMES.CART_UPDATED
            },
            {
                fieldKey: 'name',
                operator: 'is',
                value: EVENT_NAMES.CHECKOUT_STARTED
            },
            {
                fieldKey: 'name',
                operator: 'is',
                value: EVENT_NAMES.ORDER_PLACED
            }
        ]
    }

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:16

• commonFields.name is reused by both the multi-product and single-product actions, but the choice list now includes Cart Updated. The single-product action doesn’t define a products field, and send() will treat ecommerce.cart_updated as a multi-product event and call payload.products.map(...), which will throw at runtime if a user selects this option in the single-product action. Consider scoping name choices per action (e.g., override name in ecommerceSingleProduct to only allow PRODUCT_VIEWED) or add the required products field/payload shape to the single-product action if it should support cart updates.

    required: true,
    choices: [
        { label: 'Product Viewed', value: EVENT_NAMES.PRODUCT_VIEWED },
        { label: 'Cart Updated', value: EVENT_NAMES.CART_UPDATED },
        { label: 'Checkout Started', value: EVENT_NAMES.CHECKOUT_STARTED },
        { label: 'Order Placed', value: EVENT_NAMES.ORDER_PLACED },
        { label: 'Order Cancelled', value: EVENT_NAMES.ORDER_CANCELLED },
        { label: 'Order Refunded', value: EVENT_NAMES.ORDER_REFUNDED }

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:16

• commonFields.name is shared by both the multi-product ecommerce action and the single-product ecommerceSingleProduct action (see ecommerceSingleProduct/index.ts importing commonFields). Enabling CART_UPDATED here makes it selectable in the single-product action as well, but send() handles ecommerce.cart_updated as a multi-product event and will attempt to read payload.products (which the single-product payload does not have), leading to a runtime error if a user selects this event name in the single-product action. Consider scoping the name field choices per action (e.g., a separate name field for single-product that only allows PRODUCT_VIEWED), or update send() to safely handle single-product payloads for CART_UPDATED (and other multi-product events) without accessing missing fields.

    required: true,
    choices: [
        { label: 'Product Viewed', value: EVENT_NAMES.PRODUCT_VIEWED },
        { label: 'Cart Updated', value: EVENT_NAMES.CART_UPDATED },
        { label: 'Checkout Started', value: EVENT_NAMES.CHECKOUT_STARTED },
        { label: 'Order Placed', value: EVENT_NAMES.ORDER_PLACED },
        { label: 'Order Cancelled', value: EVENT_NAMES.ORDER_CANCELLED },
        { label: 'Order Refunded', value: EVENT_NAMES.ORDER_REFUNDED }

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (5)

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:173

• catalog_type is treated as an array (catalog_type.length) and then passed through as properties.type. If mappings provide a string (or other non-array), this will either send the wrong type to Braze (string instead of string[]) or behave unexpectedly. Consider guarding with Array.isArray(catalog_type) before checking length and including it, and optionally normalizing/filtering to the allowed values.

        product,
        catalog_type
      } = payload as SingleProductPayload

      const event: ProductViewedEvent = {
        ...baseEvent,
        name: EVENT_NAMES.PRODUCT_VIEWED,
        properties: {
          ...baseEvent.properties,
          ...product,
          ...(catalog_type && catalog_type.length > 0 ? { type: catalog_type } : {})
        }

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:662

• Defaulting catalog_type from $.properties.type is risky because properties.type is a very common/overloaded attribute in ecommerce payloads (often meaning product type/category), and this could unintentionally start sending Braze catalog trigger type data for existing Product Viewed events. Consider removing the default (leave unmapped by default), or sourcing from a less ambiguous property (e.g., $.properties.catalog_type) so the feature is opt-in and doesn’t conflict with existing schemas.

const catalog_type: InputField = {
    label: 'Catalog Trigger Type',
    description: 'Required to use Braze catalog trigger features. Accepted values: price_drop, back_in_stock.',
    type: 'string',
    multiple: true,
    choices: [
        { label: 'Price Drop', value: 'price_drop' },
        { label: 'Back In Stock', value: 'back_in_stock' }
    ],
    default: { '@path': '$.properties.type' },
    required: false,

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:253

• The PR description/staging plan indicates cart_updated may be sent with only cart_id + products (omitting totals). This change makes total_value required for CART_UPDATED in the UI. Either update the PR description/test plan to reflect that total_value is required for cart_updated, or relax this requirement if Braze allows cart_updated without total_value.

    required: {
        match: 'any',
        conditions: [
            {
                fieldKey: 'name',
                operator: 'is',
                value: EVENT_NAMES.CART_UPDATED
            },
            {
                fieldKey: 'name',
                operator: 'is',
                value: EVENT_NAMES.CHECKOUT_STARTED
            },

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:210

• action is cast to 'add' | 'remove' | 'replace' without runtime validation. If a mapping provides any other string, the payload will still include it and may be rejected by Braze. Consider validating action against the allowed set before including it (or emitting a clear error) rather than relying on a type cast.

          const { cart_id, action, subtotal_value, tax, shipping } = payload as Payload

          const event: CartUpdatedEvent = {
            ...multiProductEvent,
            name: EVENT_NAMES.CART_UPDATED,
            properties: {
              ...multiProductEvent.properties,
              cart_id: cart_id as string,
              ...(action ? { action: action as 'add' | 'remove' | 'replace' } : {}),
              ...(typeof subtotal_value === 'number' ? { subtotal_value } : {}),
              ...(typeof tax === 'number' ? { tax } : {}),
              ...(typeof shipping === 'number' ? { shipping } : {})
            }

packages/destination-actions/src/destinations/braze/ecommerce/types.ts:97

• There’s trailing whitespace on the tax?: number line. This can cause avoidable lint/prettier noise in future diffs; consider trimming it.

        action?: 'add' | 'remove' | 'replace'
        subtotal_value?: number
        tax?: number 
        shipping?: number

[github-actions]

New required fields detected

Warning

Your PR adds new required fields to an existing destination. Adding new required settings/mappings for a destination already in production requires updating existing customer destination configuration. Ignore this warning if this PR is for a new destination with no active customers in production.

The following required fields were added in this PR:

• Destination: Braze Cloud Mode (Actions), Action Field(s):cart_id
• Destination: Braze Cloud Mode (Actions), Action Field(s):cart_id

Add these new fields as optional instead and assume default values in perform or performBatch block.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (4)

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:1

• The PR description/test plan indicates a “cart_updated with minimal fields (just cart_id)” scenario, but total_value is now required for CART_UPDATED. Either (a) update the PR description/test plan to reflect that total_value is required, or (b) remove EVENT_NAMES.CART_UPDATED from the total_value.required conditions (and ensure the runtime payload builder + tests reflect that omission is supported).

import { InputField } from '@segment/actions-core'

packages/destination-actions/src/destinations/braze/ecommerce/tests/index.test.ts:589

• This test name says “minimal fields”, but the expected payload still includes products, total_value, and metadata. Consider renaming the test to reflect what it actually validates (e.g., “omits optional cart fields when absent”) or adjust the payload/mapping/expectation so it truly covers the “just cart_id” minimal case described in the PR.

    it('should send Cart Updated event with minimal fields correctly', async () => {

      const mapping2 = {
        ...mapping,
        name: EVENT_NAMES.CART_UPDATED,
        action: undefined,
        subtotal_value: undefined,
        tax: undefined,
        shipping: undefined
      }

packages/destination-actions/src/destinations/braze/ecommerce/tests/index.test.ts:1000

• Duplicate assertion; remove one of the expect(response.length).toBe(1) lines to reduce noise and avoid confusion during future edits.

      expect(response.length).toBe(1)

      expect(response.length).toBe(1)

packages/destination-actions/src/destinations/braze/ecommerce/generated-types.ts:58

• action is constrained by the UI field choices and runtime casting to 'add' | 'remove' | 'replace', but the generated payload type is string. Tightening this type to a union (and keeping it consistent wherever Payload.action exists) would prevent invalid values from being passed through and remove the need for repeated casts in the payload builder.

  /**
   * The cart action that was performed (add, remove, or replace).
   */
  action?: string

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (5)

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:1

• PR description states a minimal cart_updated test case with “just cart_id”, but total_value is marked required for CART_UPDATED here (and the “minimal” unit test still includes total_value). Either update the PR description to reflect that total_value is required for cart_updated, or relax this requirement if Braze accepts cart_updated without total_value.

import { InputField } from '@segment/actions-core'

packages/destination-actions/src/destinations/braze/index.ts:104

• Now that ecommerce.cart_updated is supported (and Product Added/Removed map to it), the generic “Track Calls” preset should also exclude the Segment event name for this flow (typically event != \"Cart Updated\"). Otherwise Cart Updated track calls can still be routed to trackEvent instead of the ecommerce action, causing mis-routing/duplication depending on enabled mappings.

      subscribe: 'type = "track" and event != "Order Completed" and event != "Checkout Started" and event != "Order Refunded" and event != "Order Cancelled" and event != "Product Viewed" and event != "Product Added" and event != "Product Removed"',

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:192

• Casting action to 'add' | 'remove' | 'replace' bypasses runtime validation and can emit invalid values to Braze if a mapping supplies anything outside the allowed set. Consider validating action against the allowed literals (e.g., whitelist check) and either omitting the field or throwing a clear error when invalid.

          const { cart_id, action, subtotal_value, tax, shipping } = payload as Payload

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:203

• Casting action to 'add' | 'remove' | 'replace' bypasses runtime validation and can emit invalid values to Braze if a mapping supplies anything outside the allowed set. Consider validating action against the allowed literals (e.g., whitelist check) and either omitting the field or throwing a clear error when invalid.

              cart_id: cart_id as string,
              ...(action ? { action: action as 'add' | 'remove' | 'replace' } : {}),
              ...(typeof subtotal_value === 'number' ? { subtotal_value } : {}),
              ...(typeof tax === 'number' ? { tax } : {}),
              ...(typeof shipping === 'number' ? { shipping } : {})

packages/destination-actions/src/destinations/braze/ecommerce/tests/index.test.ts:1000

• Duplicate assertion (expect(response.length).toBe(1)) appears twice in the same test; removing one will reduce noise without changing coverage.

      expect(response.length).toBe(1)

      expect(response.length).toBe(1)

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (4)

packages/destination-actions/src/destinations/braze/ecommerce/fields.ts:661

• The PR description and test plan refer to sending catalog_type, but the field defaults to reading $.properties.type (and the tests also set properties.type). This mismatch will confuse users and likely break expected behavior if they send properties.catalog_type; either update the default (and preset mappings/tests) to $.properties.catalog_type, or update the PR description/test plan and field description to explicitly document that the source field is properties.type and the destination field becomes Braze properties.type.

const catalog_type: InputField = {
    label: 'Catalog Trigger Type',
    description: 'Required to use Braze catalog trigger features. Accepted values: price_drop, back_in_stock.',
    type: 'string',
    multiple: true,
    choices: [
        { label: 'Price Drop', value: 'price_drop' },
        { label: 'Back In Stock', value: 'back_in_stock' }
    ],
    default: { '@path': '$.properties.type' },

packages/destination-actions/src/destinations/braze/ecommerce/functions.ts:205

• action is passed through for any truthy string (the as 'add' | 'remove' | 'replace' cast is compile-time only), so invalid values can still be sent to Braze (e.g., via custom mappings). Consider enforcing the allowed set at runtime (only include when action is exactly add|remove|replace, otherwise omit or throw a clear validation error) to prevent sending invalid payloads.

      switch(name) {
        case EVENT_NAMES.CART_UPDATED: {
          const { cart_id, action, subtotal_value, tax, shipping } = payload as Payload

          const event: CartUpdatedEvent = {
            ...multiProductEvent,
            name: EVENT_NAMES.CART_UPDATED,
            properties: {
              ...multiProductEvent.properties,
              cart_id: cart_id as string,
              ...(action ? { action: action as 'add' | 'remove' | 'replace' } : {}),
              ...(typeof subtotal_value === 'number' ? { subtotal_value } : {}),
              ...(typeof tax === 'number' ? { tax } : {}),
              ...(typeof shipping === 'number' ? { shipping } : {})
            }
          }

packages/destination-actions/src/destinations/braze/ecommerce/tests/index.test.ts:1000

• This test contains a duplicated assertion (expect(response.length).toBe(1)) back-to-back. Please remove the duplicate (or replace it with a different assertion that adds coverage) to keep the test intent clear.

      expect(response.length).toBe(1)

      expect(response.length).toBe(1)

packages/destination-actions/src/destinations/braze/ecommerceSingleProduct/generated-types.ts:50

• This payload type is for ecommerceSingleProduct but the cart_id docstring now references cart_updated, which this action does not emit. Consider adjusting the shared field description to be action-appropriate (or making the description more neutral, e.g., describing cart_id usage without referencing specific events) to reduce confusion for consumers reading the generated types.

   * Unique identifier for the cart. Required for cart_updated. For checkout and order events, if no value is passed, Braze will determine a default value for the user cart mapping.
   */
  cart_id?: string