E-Commerce Event Spec

This page defines all standard e-commerce events for Datafly Signal. Implement these events to enable accurate server-side delivery to advertising and analytics platforms.

💡

These event names match GA4’s recommended events. If you’re migrating from Google Tag Manager, your existing event names work as-is.

All events are sent via _df.track(). Properties are passed as a flat object in the second argument.

Browsing Events

`view_item_list`

Fired when a user views a product listing, category page, or search results grid.

_df.track('view_item_list', {
  item_list_id: 'womens-jackets',
  item_list_name: 'Women — Jackets',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, index: 0, item_category: 'Jackets', item_brand: 'NorthEdge' },
    { item_id: 'PKT-002', item_name: 'Puffer Jacket', price: 99.99, index: 1, item_category: 'Jackets', item_brand: 'NorthEdge' }
  ]
})

Property	Type	Required	Description
`item_list_id`	string	Optional	Machine-readable identifier for the list or collection
`item_list_name`	string	Optional	Human-readable name of the list or category being browsed
`items`	array	Optional	Array of item objects displayed in the list (see Items Array Schema)

`select_item`

Fired when a user clicks on a product within a list or search results.

_df.track('select_item', {
  item_list_id: 'womens-jackets',
  item_list_name: 'Women — Jackets',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, index: 0, item_category: 'Jackets', item_brand: 'NorthEdge' }
  ]
})

Property	Type	Required	Description
`item_list_id`	string	Optional	Identifier of the list the product was selected from
`item_list_name`	string	Optional	Name of the list the product was selected from
`items`	array	Optional	Array containing the selected item (see Items Array Schema)

`search`

Fired when a user submits a search query for products.

_df.track('search', {
  search_term: 'waterproof jacket'
})

Property	Type	Required	Description
`search_term`	string	Required	The search term entered by the user

`view_promotion`

Fired when a promotional banner or hero image is visible to the user.

_df.track('view_promotion', {
  promotion_id: 'SUMMER24',
  promotion_name: 'Summer Sale Banner',
  creative_name: 'summer-sale-hero-v2.jpg',
  creative_slot: 'homepage-hero'
})

Property	Type	Required	Description
`promotion_id`	string	Optional	Identifier for the promotion
`promotion_name`	string	Optional	Human-readable name of the promotion
`creative_name`	string	Optional	Name or URL of the creative asset shown
`creative_slot`	string	Optional	Slot or placement where the promotion appeared

`select_promotion`

Fired when a user clicks on a promotional banner or creative.

_df.track('select_promotion', {
  promotion_id: 'SUMMER24',
  promotion_name: 'Summer Sale Banner',
  creative_name: 'summer-sale-hero-v2.jpg',
  creative_slot: 'homepage-hero'
})

Property	Type	Required	Description
`promotion_id`	string	Optional	Identifier for the promotion
`promotion_name`	string	Optional	Human-readable name of the promotion
`creative_name`	string	Optional	Name or URL of the creative asset shown
`creative_slot`	string	Optional	Slot or placement where the promotion appeared

Product Events

`view_item`

Fired when a user lands on a product detail page. Also accepted as view_content.

_df.track('view_item', {
  currency: 'GBP',
  value: 129.99,
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Women > Jackets',
      item_brand: 'NorthEdge',
      item_variant: 'Black / M',
      price: 129.99,
      currency: 'GBP',
      quantity: 1
    }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code (e.g. `GBP`, `USD`)
`value`	number	Optional	Monetary value of the event
`items`	array	Optional	Array containing the viewed item (see Items Array Schema)

`add_to_cart`

Fired when a user adds a product to their cart.

_df.track('add_to_cart', {
  currency: 'GBP',
  value: 129.99,
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Women > Jackets',
      item_brand: 'NorthEdge',
      item_variant: 'Black / M',
      price: 129.99,
      currency: 'GBP',
      quantity: 1
    }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Monetary value of the items added
`items`	array	Optional	Array of items added to the cart (see Items Array Schema)

`remove_from_cart`

Fired when a user removes a product from their cart.

_df.track('remove_from_cart', {
  currency: 'GBP',
  value: 129.99,
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Women > Jackets',
      item_brand: 'NorthEdge',
      item_variant: 'Black / M',
      price: 129.99,
      currency: 'GBP',
      quantity: 1
    }
  ]
})

Accepts the same properties as add_to_cart.

Cart & Checkout Events

`view_cart`

Fired when a user opens or views their shopping cart.

_df.track('view_cart', {
  currency: 'GBP',
  value: 259.98,
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 2, currency: 'GBP' }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Total cart value
`items`	array	Optional	Items currently in the cart (see Items Array Schema)

`begin_checkout`

Fired when a user initiates the checkout process.

_df.track('begin_checkout', {
  currency: 'GBP',
  value: 259.98,
  coupon: 'SAVE10',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 2, currency: 'GBP' }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Total value of the checkout
`coupon`	string	Optional	Coupon code applied
`items`	array	Optional	Items in the checkout (see Items Array Schema)

`add_shipping_info`

Fired when a user submits their shipping information during checkout.

_df.track('add_shipping_info', {
  currency: 'GBP',
  value: 259.98,
  coupon: 'SAVE10',
  shipping_tier: 'Express',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 2, currency: 'GBP' }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Total value of the checkout
`coupon`	string	Optional	Coupon code applied
`shipping_tier`	string	Optional	Shipping tier selected (e.g. `Express`, `Standard`, `Next Day`)
`items`	array	Optional	Items in the checkout (see Items Array Schema)

`add_payment_info`

Fired when a user submits their payment details.

_df.track('add_payment_info', {
  currency: 'GBP',
  value: 259.98,
  coupon: 'SAVE10',
  payment_type: 'credit_card',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 2, currency: 'GBP' }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Total value of the checkout
`coupon`	string	Optional	Coupon code applied
`payment_type`	string	Optional	Payment method type (e.g. `credit_card`, `paypal`, `apple_pay`)
`items`	array	Optional	Items in the checkout (see Items Array Schema)

Order Events

`purchase`

Fired on the order confirmation page after a successful purchase. This is the most important e-commerce event — ensure it fires reliably.

_df.track('purchase', {
  transaction_id: 'ORD-10042',
  value: 259.98,
  currency: 'GBP',
  tax: 43.33,
  shipping: 10.00,
  coupon: 'SAVE10',
  affiliation: 'NorthEdge Online Store',
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Jackets',
      item_brand: 'NorthEdge',
      item_variant: 'Black / M',
      price: 129.99,
      quantity: 2,
      currency: 'GBP'
    }
  ]
})

Property	Type	Required	Description
`transaction_id`	string	Required	Unique order identifier — used for deduplication
`value`	number	Optional	Total revenue including tax and shipping
`currency`	string	Optional	ISO 4217 currency code
`tax`	number	Optional	Tax amount
`shipping`	number	Optional	Shipping cost
`coupon`	string	Optional	Coupon code applied to the order
`affiliation`	string	Optional	Store or affiliate that generated the order
`items`	array	Optional	Items purchased (see Items Array Schema)

⚠️

Always send transaction_id on purchase events for deduplication. Platforms like Meta CAPI and GA4 use the transaction ID to prevent double-counting alongside browser-side events.

`refund`

Fired when a full or partial refund is issued. For partial refunds, include only the items being refunded.

_df.track('refund', {
  transaction_id: 'ORD-10042',
  value: 129.99,
  currency: 'GBP',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 1 }
  ]
})

Property	Type	Required	Description
`transaction_id`	string	Required	Identifier of the order being refunded
`value`	number	Optional	Amount refunded
`currency`	string	Optional	ISO 4217 currency code
`items`	array	Optional	Items being refunded. Omit for full order refunds; include specific items for partial refunds.

Wishlist Events

`add_to_wishlist`

Fired when a user saves a product to their wishlist.

_df.track('add_to_wishlist', {
  currency: 'GBP',
  value: 129.99,
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Jackets',
      item_brand: 'NorthEdge',
      price: 129.99
    }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Monetary value of the items added
`items`	array	Optional	Array of items added to the wishlist (see Items Array Schema)

`remove_from_wishlist`

Fired when a user removes a product from their wishlist.

_df.track('remove_from_wishlist', {
  currency: 'GBP',
  value: 129.99,
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      price: 129.99
    }
  ]
})

Accepts the same properties as add_to_wishlist.

Account Events

`sign_up`

Fired when a user completes account registration.

_df.track('sign_up', {
  method: 'email'
})

Property	Type	Required	Description
`method`	string	Optional	Registration method (e.g. `email`, `google`, `facebook`)

`login`

Fired when a user signs in to their account.

_df.track('login', {
  method: 'email'
})

Property	Type	Required	Description
`method`	string	Optional	Login method (e.g. `email`, `google`, `facebook`)

Items Array Schema

💡

Several events accept an items array. Each object in the array can include the following properties. The items[] array uses GA4-style field names. Signal’s server-side blueprints automatically transform these to vendor-specific formats (e.g., Meta’s contents[] with id/title fields).

Property	Type	Description
`item_id`	string	Your internal product ID or SKU
`item_name`	string	Product display name
`item_category`	string	Product category or breadcrumb path
`item_brand`	string	Brand name
`item_variant`	string	Selected variant (e.g. `Blue / XL`)
`price`	number	Unit price
`quantity`	number	Number of units (relevant in cart/order contexts)
`index`	number	Position in list (0-indexed, relevant in list/search contexts)
`currency`	string	ISO 4217 currency code
`coupon`	string	Item-level coupon code if applicable
`discount`	number	Monetary discount applied to this item
`affiliation`	string	Store or affiliate for this item
`item_list_id`	string	Identifier of the list the item was shown in
`item_list_name`	string	Name of the list the item was shown in

Vendor Mapping

The table below shows how Datafly Signal maps e-commerce events to the native event names expected by each vendor’s server-side API. Signal uses the GA4-style event names as its canonical format, and blueprints handle the transformation to vendor-specific payloads.

Signal Event	GA4	Meta CAPI	TikTok Events API
`view_item`	`view_item`	`ViewContent`	`ViewContent`
`view_item_list`	`view_item_list`	`ViewContent`	`ViewContent`
`select_item`	`select_item`	`ViewContent`	`ClickButton`
`add_to_cart`	`add_to_cart`	`AddToCart`	`AddToCart`
`remove_from_cart`	`remove_from_cart`	(custom)	(custom)
`view_cart`	`view_cart`	`ViewContent`	`ViewContent`
`begin_checkout`	`begin_checkout`	`InitiateCheckout`	`InitiateCheckout`
`add_payment_info`	`add_payment_info`	`AddPaymentInfo`	`AddPaymentInfo`
`add_shipping_info`	`add_shipping_info`	(custom)	(custom)
`purchase`	`purchase`	`Purchase`	`PlaceAnOrder`
`refund`	`refund`	(custom)	(custom)
`search`	`search`	`Search`	`Search`
`view_promotion`	`view_promotion`	(custom)	(custom)
`select_promotion`	`select_promotion`	(custom)	(custom)
`add_to_wishlist`	`add_to_wishlist`	`AddToWishlist`	`AddToWishlist`
`sign_up`	`sign_up`	`CompleteRegistration`	`CompleteRegistration`
`login`	`login`	(custom)	(custom)

Overview Publishing