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

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

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

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

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

`view_search_results`

Fired when search results are rendered to the user. Pairs with search to capture result quality and zero-result searches.

datafly.track('view_search_results', {
  search_term: 'waterproof jacket',
  results_count: 24,
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, index: 0, item_category: 'Jackets', item_brand: 'NorthEdge' }
  ]
})

Property	Type	Required	Description
`search_term`	string	Required	The search term that produced these results
`results_count`	number	Optional	Number of results returned (use `0` for no-result searches)
`items`	array	Optional	Array of items shown in the results (see Items Array Schema)

`products_filtered`

Fired when a user applies a filter (size, colour, price band, brand, etc.) to a product list or search results.

datafly.track('products_filtered', {
  item_list_id: 'womens-jackets',
  item_list_name: 'Women — Jackets',
  filters: [
    { type: 'colour', value: 'black' },
    { type: 'size', value: 'M' }
  ],
  results_count: 12
})

Property	Type	Required	Description
`item_list_id`	string	Optional	Identifier of the list being filtered
`item_list_name`	string	Optional	Name of the list being filtered
`filters`	array	Optional	Array of `{ type, value }` objects describing each active filter
`results_count`	number	Optional	Number of products remaining after filtering

`products_sorted`

Fired when a user changes the sort order of a product list or search results.

datafly.track('products_sorted', {
  item_list_id: 'womens-jackets',
  item_list_name: 'Women — Jackets',
  sort_by: 'price',
  sort_order: 'asc'
})

Property	Type	Required	Description
`item_list_id`	string	Optional	Identifier of the list being sorted
`item_list_name`	string	Optional	Name of the list being sorted
`sort_by`	string	Optional	Field the list is sorted by (e.g. `price`, `popularity`, `newest`)
`sort_order`	string	Optional	Sort direction (`asc` or `desc`)

`view_promotion`

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

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

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

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

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

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

`product_reviewed`

Fired when a user submits a product review or rating.

datafly.track('product_reviewed', {
  rating: 5,
  review_id: 'REV-88213',
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Jackets',
      item_brand: 'NorthEdge'
    }
  ]
})

Property	Type	Required	Description
`rating`	number	Optional	Star rating submitted (e.g. `1`–`5`)
`review_id`	string	Optional	Identifier of the submitted review
`items`	array	Optional	Array containing the reviewed item (see Items Array Schema)

`product_shared`

Fired when a user shares a product via social, email, or a copied link.

datafly.track('product_shared', {
  share_method: 'whatsapp',
  items: [
    {
      item_id: 'PKT-001',
      item_name: 'Parka Jacket',
      item_category: 'Jackets',
      item_brand: 'NorthEdge'
    }
  ]
})

Property	Type	Required	Description
`share_method`	string	Optional	Channel used to share (e.g. `whatsapp`, `email`, `copy_link`, `facebook`)
`items`	array	Optional	Array containing the shared item (see Items Array Schema)

Cart & Checkout Events

`view_cart`

Fired when a user opens or views their shopping cart.

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

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

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

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

`coupon_applied`

Fired when a discount or promo code is successfully applied to the cart or checkout.

datafly.track('coupon_applied', {
  coupon: 'SAVE10',
  currency: 'GBP',
  discount: 26.00,
  value: 233.98
})

Property	Type	Required	Description
`coupon`	string	Required	The coupon or promo code applied
`currency`	string	Optional	ISO 4217 currency code
`discount`	number	Optional	Monetary discount granted by the coupon
`value`	number	Optional	Cart value after the discount is applied

`coupon_denied`

Fired when a discount or promo code is rejected (invalid, expired, or ineligible).

datafly.track('coupon_denied', {
  coupon: 'SAVE10',
  reason: 'expired'
})

Property	Type	Required	Description
`coupon`	string	Required	The coupon or promo code that was rejected
`reason`	string	Optional	Why the coupon was denied (e.g. `expired`, `invalid`, `minimum_not_met`, `not_eligible`)

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.

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

`order_shipped`

Fired from your backend when an order is dispatched. Typically sent server-to-server rather than from the browser, since shipment happens after the session ends.

datafly.track('order_shipped', {
  transaction_id: 'ORD-10042',
  value: 259.98,
  currency: 'GBP',
  shipping_tier: 'Express',
  carrier: 'Royal Mail',
  tracking_number: 'RM123456789GB',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', price: 129.99, quantity: 2, currency: 'GBP' }
  ]
})

Property	Type	Required	Description
`transaction_id`	string	Required	Identifier of the order being shipped
`value`	number	Optional	Total value of the shipped order
`currency`	string	Optional	ISO 4217 currency code
`shipping_tier`	string	Optional	Shipping tier (e.g. `Express`, `Standard`)
`carrier`	string	Optional	Carrier handling the delivery
`tracking_number`	string	Optional	Carrier tracking reference
`items`	array	Optional	Items in the shipment (see Items Array Schema)

`refund`

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

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

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

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

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

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

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

Retention & Lead Events

`generate_lead`

Fired when a user submits a non-purchase intent form — back-in-stock alerts, price-drop alerts, or a sales enquiry. Never pass raw email or phone here; the contact PII is hashed server-side via Signal’s identity blueprint.

datafly.track('generate_lead', {
  currency: 'GBP',
  value: 129.99,
  lead_type: 'back_in_stock',
  items: [
    { item_id: 'PKT-001', item_name: 'Parka Jacket', item_category: 'Jackets' }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Estimated value of the lead
`lead_type`	string	Optional	Nature of the lead (e.g. `back_in_stock`, `price_drop`, `enquiry`)
`items`	array	Optional	Related items (see Items Array Schema)

`join_group`

Fired when a user subscribes to a newsletter, loyalty programme, or marketing list. Do not include the email address — Signal hashes contact identifiers server-side.

datafly.track('join_group', {
  group_id: 'newsletter',
  method: 'footer_form'
})

Property	Type	Required	Description
`group_id`	string	Optional	Identifier of the list or programme joined (e.g. `newsletter`, `loyalty`)
`method`	string	Optional	Where the subscription happened (e.g. `footer_form`, `checkout`, `popup`)

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`
`search`	`search`	`Search`	`Search`
`view_search_results`	`view_search_results`	`Search`	`Search`
`products_filtered`	`products_filtered`	(custom)	(custom)
`products_sorted`	`products_sorted`	(custom)	(custom)
`view_promotion`	`view_promotion`	(custom)	(custom)
`select_promotion`	`select_promotion`	(custom)	(custom)
`add_to_cart`	`add_to_cart`	`AddToCart`	`AddToCart`
`remove_from_cart`	`remove_from_cart`	(custom)	(custom)
`product_reviewed`	`product_reviewed`	(custom)	(custom)
`product_shared`	`product_shared`	(custom)	(custom)
`view_cart`	`view_cart`	`ViewContent`	`ViewContent`
`begin_checkout`	`begin_checkout`	`InitiateCheckout`	`InitiateCheckout`
`add_shipping_info`	`add_shipping_info`	(custom)	(custom)
`add_payment_info`	`add_payment_info`	`AddPaymentInfo`	`AddPaymentInfo`
`coupon_applied`	`coupon_applied`	(custom)	(custom)
`coupon_denied`	`coupon_denied`	(custom)	(custom)
`purchase`	`purchase`	`Purchase`	`CompletePayment`
`order_shipped`	`order_shipped`	(custom)	(custom)
`refund`	`refund`	(custom)	(custom)
`add_to_wishlist`	`add_to_wishlist`	`AddToWishlist`	`AddToWishlist`
`remove_from_wishlist`	`remove_from_wishlist`	(custom)	(custom)
`sign_up`	`sign_up`	`CompleteRegistration`	`CompleteRegistration`
`login`	`login`	(custom)	(custom)
`generate_lead`	`generate_lead`	`Lead`	`SubmitForm`
`join_group`	`join_group`	`Subscribe`	`Subscribe`

Overview Publishing