Ecommerce events

Ecommerce events are where Luigi’s Box learns what creates value. Clicks show interest, but conversions and completed transactions show intent and revenue.

Think in funnel steps

The common ecommerce funnel looks like this:

1. The user sees a result list
2. The user clicks an item
3. The user performs a stronger action such as add to cart
4. The user completes a purchase

In v1, steps 2 and 3 use the click event family, while the final purchase uses transaction.

Click vs conversion

Result click

Use a normal click event when the user opens a product from search, autocomplete, product listing, or a recommendation widget.

{
  "type": "click",
  "id": "4f2e4fe6-147e-4c33-9681-2da7a0d140d2",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "click",
    "resource_identifier": "product_123"
  }
}

Micro-conversion

For actions like add to cart, add to wishlist, or add to favorites, keep the outer event type as click and change action.type.

{
  "type": "click",
  "id": "2780c816-5425-4128-a339-3b4e45e9a06a",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "add-to-cart",
    "resource_identifier": "product_123"
  }
}

The supported model is flexible here. Any action.type other than click is treated as a conversion signal.

Where to emit conversion events

Send conversion events from every place where the action can happen:

• search results page
• autocomplete dropdown interaction flow
• product listing page
• recommendation widget
• product detail page
• mobile product screen

That gives Luigi’s Box the best chance to attribute the conversion to the right discovery interaction.

Transaction events

Use transaction only after the order is completed.

{
  "type": "transaction",
  "id": "03dd16c3-4dd5-44c0-87c4-b3a652c06a87",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "customer_id": "customer-42",
  "items": [
    {
      "title": "White shirt, round neck, short sleeves",
      "url": "9339993",
      "count": 1,
      "total_price": 19,
      "was_discounted": false,
      "was_volume_discounted": false
    },
    {
      "title": "Brown overcoat",
      "url": "299299",
      "count": 2,
      "total_price": 268.5,
      "was_discounted": true,
      "was_volume_discounted": false
    }
  ]
}

Transaction item rules

Field	Required	Description
url	✓	The indexed identity of the purchased item
count	✓	Quantity purchased
total_price	✓	Final line-item total after quantity and discounts
title		Useful for reporting readability
was_discounted		true when the item was discounted below its catalog price
was_volume_discounted		true when a quantity-based discount was applied

Important pricing rule

total_price should be the final amount actually paid for that line item, not the catalog unit price.

Common patterns

Add to wishlist

{
  "type": "click",
  "id": "53b8d25c-e071-44dd-bba4-e8506c6d00df",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "add-to-wishlist",
    "resource_identifier": "product_123"
  }
}

Buy-now flow

If your storefront supports a direct “buy now” action before checkout completes, treat that as a conversion:

{
  "type": "click",
  "id": "e18a3b89-5d34-43ba-b659-f4763eb11f79",
  "tracker_id": "YOUR_TRACKER_ID",
  "client_id": "web-user-1",
  "action": {
    "type": "buy",
    "resource_identifier": "product_123"
  }
}

Then send the transaction once the purchase is finalized.

Accuracy checklist

• Use the same object identity here as in indexing and list events
• Keep client_id stable across the full journey
• Emit conversion events from every relevant UI surface
• Send the full purchased basket in transaction
• Use final paid values in total_price

Next steps

• Review the Event API reference
• Make sure discovery surfaces are tracked with search and discovery
• Validate payloads with the analytics debugging guide