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.

All events are sent via _df.track(). Properties listed here are sent inside the properties object.

Browsing Events

`product_list_viewed`

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

_df.track('product_list_viewed', {
  list_id: 'womens-jackets',
  category: 'Women > Jackets',
  products: [
    { product_id: 'PKT-001', sku: 'PKT-001-BLK-M', name: 'Parka Jacket', price: 129.99, position: 1, category: 'Jackets', brand: 'NorthEdge' },
    { product_id: 'PKT-002', sku: 'PKT-002-NAV-L', name: 'Puffer Jacket', price: 99.99, position: 2, category: 'Jackets', brand: 'NorthEdge' }
  ]
})

Property	Type	Required	Description
`list_id`	string	Optional	Machine-readable identifier for the list or collection
`category`	string	Optional	Category or section being browsed
`products`	array	Optional	Array of product objects displayed in the list (see schema below)

`product_searched`

Fired when a user submits a search query for products.

_df.track('product_searched', {
  query: 'waterproof jacket'
})

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

`promotion_viewed`

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

_df.track('promotion_viewed', {
  promotion_id: 'SUMMER24',
  name: 'Summer Sale Banner',
  creative: 'summer-sale-hero-v2.jpg',
  position: 'homepage-hero'
})

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

`promotion_clicked`

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

_df.track('promotion_clicked', {
  promotion_id: 'SUMMER24',
  name: 'Summer Sale Banner',
  creative: 'summer-sale-hero-v2.jpg',
  position: 'homepage-hero'
})

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

Product Events

`product_viewed`

Fired when a user lands on a product detail page.

_df.track('product_viewed', {
  product_id: 'PKT-001',
  sku: 'PKT-001-BLK-M',
  name: 'Parka Jacket',
  price: 129.99,
  currency: 'GBP',
  category: 'Women > Jackets',
  brand: 'NorthEdge',
  variant: 'Black / M',
  url: 'https://example.com/products/parka-jacket',
  image_url: 'https://example.com/images/parka-jacket-blk.jpg'
})

Property	Type	Required	Description
`product_id`	string	Optional	Your internal product ID
`sku`	string	Optional	Stock keeping unit for the specific variant
`name`	string	Optional	Product display name
`price`	number	Optional	Unit price
`currency`	string	Optional	ISO 4217 currency code (e.g. `GBP`, `USD`)
`category`	string	Optional	Product category or breadcrumb path
`brand`	string	Optional	Brand name
`variant`	string	Optional	Selected variant (e.g. `Blue / XL`)
`url`	string	Optional	Canonical URL of the product page
`image_url`	string	Optional	URL of the primary product image

`product_added`

Fired when a user adds a product to their cart.

_df.track('product_added', {
  product_id: 'PKT-001',
  sku: 'PKT-001-BLK-M',
  name: 'Parka Jacket',
  price: 129.99,
  currency: 'GBP',
  category: 'Women > Jackets',
  brand: 'NorthEdge',
  variant: 'Black / M',
  quantity: 1
})

Property	Type	Required	Description
`product_id`	string	Optional	Your internal product ID
`sku`	string	Optional	Stock keeping unit
`name`	string	Optional	Product display name
`price`	number	Optional	Unit price
`currency`	string	Optional	ISO 4217 currency code
`category`	string	Optional	Product category
`brand`	string	Optional	Brand name
`variant`	string	Optional	Selected variant
`quantity`	number	Optional	Number of units added (defaults to `1` if omitted)

`product_removed`

Fired when a user removes a product from their cart.

_df.track('product_removed', {
  product_id: 'PKT-001',
  sku: 'PKT-001-BLK-M',
  name: 'Parka Jacket',
  price: 129.99,
  currency: 'GBP',
  category: 'Women > Jackets',
  brand: 'NorthEdge',
  variant: 'Black / M',
  quantity: 1
})

Accepts the same properties as product_added.

`product_reviewed`

Fired when a user submits a review for a product.

_df.track('product_reviewed', {
  product_id: 'PKT-001',
  review_id: 'rev-8821',
  review_body: 'Great jacket, really warm and the sizing is accurate.',
  rating: 5
})

Property	Type	Required	Description
`product_id`	string	Required	Product being reviewed
`review_id`	string	Required	Unique ID for this review submission
`review_body`	string	Required	Text content of the review
`rating`	number	Required	Numeric rating (e.g. 1–5)

Cart & Checkout Events

`cart_viewed`

Fired when a user opens or views their shopping cart.

_df.track('cart_viewed', {
  cart_id: 'cart-f3a9c2',
  currency: 'GBP',
  total: 259.98,
  products: [
    { product_id: 'PKT-001', name: 'Parka Jacket', price: 129.99, quantity: 2 }
  ]
})

Property	Type	Required	Description
`cart_id`	string	Optional	Unique identifier for the cart session
`products`	array	Optional	Products currently in the cart (see schema below)
`total`	number	Optional	Cart total value
`currency`	string	Optional	ISO 4217 currency code

`checkout_started`

Fired when a user initiates the checkout process.

_df.track('checkout_started', {
  order_id: 'ORD-10042',
  revenue: 259.98,
  currency: 'GBP',
  coupon: 'SAVE10',
  products: [
    { product_id: 'PKT-001', name: 'Parka Jacket', price: 129.99, quantity: 2 }
  ]
})

Property	Type	Required	Description
`order_id`	string	Optional	Order identifier (may be provisional at this stage)
`revenue`	number	Optional	Total revenue value of the checkout
`currency`	string	Optional	ISO 4217 currency code
`coupon`	string	Optional	Coupon code applied
`products`	array	Optional	Products in the checkout (see schema below)

`checkout_step_viewed`

Fired when a user arrives at a distinct step in the checkout flow (e.g. address, shipping, payment).

_df.track('checkout_step_viewed', {
  checkout_id: 'chk-a83f1',
  step: 2,
  step_name: 'Shipping Method'
})

Property	Type	Required	Description
`checkout_id`	string	Required	Unique identifier for this checkout session
`step`	number	Required	Step number (1-indexed)
`step_name`	string	Required	Human-readable name for the step

`checkout_step_completed`

Fired when a user completes a checkout step and advances to the next.

_df.track('checkout_step_completed', {
  checkout_id: 'chk-a83f1',
  step: 2,
  step_name: 'Shipping Method',
  option: 'Express Delivery'
})

Property	Type	Required	Description
`checkout_id`	string	Required	Unique identifier for this checkout session
`step`	number	Required	Step number completed
`step_name`	string	Required	Human-readable name for the step
`option`	string	Optional	Option selected at this step (e.g. payment method, shipping tier)

`payment_info_entered`

Fired when a user submits their payment details.

_df.track('payment_info_entered', {
  checkout_id: 'chk-a83f1',
  payment_method: 'credit_card'
})

Property	Type	Required	Description
`checkout_id`	string	Optional	Checkout session identifier
`payment_method`	string	Optional	Payment method type (e.g. `credit_card`, `paypal`, `apple_pay`)

Order Events

`order_completed`

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

_df.track('order_completed', {
  order_id: 'ORD-10042',
  revenue: 259.98,
  subtotal: 249.98,
  tax: 43.33,
  shipping: 10.00,
  currency: 'GBP',
  coupon: 'SAVE10',
  affiliation: 'NorthEdge Online Store',
  products: [
    { product_id: 'PKT-001', sku: 'PKT-001-BLK-M', name: 'Parka Jacket', price: 129.99, quantity: 2, category: 'Jackets', brand: 'NorthEdge' }
  ]
})

Property	Type	Required	Description
`order_id`	string	Required	Unique order identifier — used for deduplication
`revenue`	number	Optional	Total revenue including tax and shipping
`subtotal`	number	Optional	Revenue before tax and shipping
`tax`	number	Optional	Tax amount
`shipping`	number	Optional	Shipping cost
`currency`	string	Optional	ISO 4217 currency code
`coupon`	string	Optional	Coupon code applied to the order
`affiliation`	string	Optional	Store or affiliate that generated the order
`products`	array	Optional	Products purchased (see schema below)

⚠️

Always send order_id to enable server-side deduplication. Platforms like Meta CAPI and GA4 use the order ID to prevent double-counting alongside browser-side events.

`order_updated`

Fired when an existing order is modified (e.g. quantity change, address update).

_df.track('order_updated', {
  order_id: 'ORD-10042',
  revenue: 389.97,
  products: [
    { product_id: 'PKT-001', name: 'Parka Jacket', price: 129.99, quantity: 3 }
  ]
})

Property	Type	Required	Description
`order_id`	string	Required	Identifier of the order being updated
`revenue`	number	Optional	Updated total revenue
`products`	array	Optional	Updated product list

`order_cancelled`

Fired when an order is cancelled before fulfilment.

_df.track('order_cancelled', {
  order_id: 'ORD-10042',
  revenue: 259.98,
  reason: 'customer_request'
})

Property	Type	Required	Description
`order_id`	string	Required	Identifier of the cancelled order
`revenue`	number	Optional	Revenue value of the cancelled order
`reason`	string	Optional	Reason for cancellation (e.g. `customer_request`, `out_of_stock`)

`order_refunded`

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

_df.track('order_refunded', {
  order_id: 'ORD-10042',
  revenue: 129.99,
  products: [
    { product_id: 'PKT-001', name: 'Parka Jacket', price: 129.99, quantity: 1 }
  ]
})

Property	Type	Required	Description
`order_id`	string	Required	Identifier of the order being refunded
`revenue`	number	Optional	Amount refunded
`products`	array	Optional	Products being refunded. Omit for full order refunds; include specific items for partial refunds.

Coupon Events

`coupon_applied`

Fired when a coupon code is successfully applied to an order or cart.

_df.track('coupon_applied', {
  order_id: 'ORD-10042',
  coupon_id: 'SAVE10',
  coupon_name: '10% Off Summer Sale',
  discount: 25.99
})

Property	Type	Required	Description
`order_id`	string	Optional	Order the coupon was applied to
`coupon_id`	string	Optional	Machine-readable coupon code
`coupon_name`	string	Optional	Human-readable coupon name
`discount`	number	Optional	Monetary discount value applied

`coupon_removed`

Fired when a coupon is removed from an order or cart.

_df.track('coupon_removed', {
  order_id: 'ORD-10042',
  coupon_id: 'SAVE10'
})

Property	Type	Required	Description
`order_id`	string	Optional	Order the coupon was removed from
`coupon_id`	string	Optional	Machine-readable coupon code

Wishlist Events

`wishlist_product_added`

Fired when a user saves a product to their wishlist.

_df.track('wishlist_product_added', {
  wishlist_id: 'wl-user-3812',
  wishlist_name: 'My Favourites',
  product_id: 'PKT-001',
  name: 'Parka Jacket',
  price: 129.99
})

Property	Type	Required	Description
`wishlist_id`	string	Optional	Unique identifier for the wishlist
`wishlist_name`	string	Optional	Display name of the wishlist
`product_id`	string	Optional	Product added to the wishlist
`name`	string	Optional	Product display name
`price`	number	Optional	Product price at time of saving

`wishlist_product_removed`

Fired when a user removes a product from their wishlist.

_df.track('wishlist_product_removed', {
  wishlist_id: 'wl-user-3812',
  wishlist_name: 'My Favourites',
  product_id: 'PKT-001',
  name: 'Parka Jacket',
  price: 129.99
})

Accepts the same properties as wishlist_product_added.

Products Array Schema

💡

Several events accept a products array. Each object in the array can include the following properties. All are optional unless noted.

Property	Type	Description
`product_id`	string	Your internal product ID
`sku`	string	Stock keeping unit for the specific variant
`name`	string	Product display name
`price`	number	Unit price
`quantity`	number	Number of units (relevant in cart/order contexts)
`position`	number	Position in list (relevant in list/search contexts, 1-indexed)
`category`	string	Product category
`brand`	string	Brand name
`variant`	string	Selected variant (e.g. `Blue / XL`)
`currency`	string	ISO 4217 currency code
`url`	string	Product page URL
`image_url`	string	Primary product image URL

Vendor Mapping

The table below shows how Datafly Signal maps key e-commerce events to the native event names expected by each vendor’s server-side API.

Signal Event	GA4	Meta CAPI	TikTok Events API
`product_viewed`	`view_item`	`ViewContent`	`ViewContent`
`product_added`	`add_to_cart`	`AddToCart`	`AddToCart`
`product_list_viewed`	`view_item_list`	`ViewContent`	`ViewContent`
`product_searched`	`search`	`Search`	`Search`
`checkout_started`	`begin_checkout`	`InitiateCheckout`	`InitiateCheckout`
`payment_info_entered`	`add_payment_info`	`AddPaymentInfo`	`AddPaymentInfo`
`order_completed`	`purchase`	`Purchase`	`PlaceAnOrder`
`order_refunded`	`refund`	(custom event)	(custom event)
`promotion_viewed`	`view_promotion`	(custom event)	(custom event)
`promotion_clicked`	`select_promotion`	(custom event)	(custom event)
`wishlist_product_added`	`add_to_wishlist`	`AddToWishlist`	`AddToWishlist`

Overview Publishing