---
title: Ecommerce events
description: Track add-to-cart, wishlist, and purchase behavior with the supported Luigi's Box Events API v1.
slug: analytics/api_guides/ecommerce-events
docKind: guide
hub: analytics
---

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.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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

```json
{
  "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:

```json
{
  "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](/analytics/api/events/)
- Make sure discovery surfaces are tracked with [search and discovery](/analytics/api_guides/search-and-discovery/)
- Validate payloads with the [analytics debugging guide](/analytics/debugging/)