> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Send impressions, clicks, add-to-carts, product views and purchases to Depict. The request format, the fields of each event type, the response and the limits.

Depict learns from what shoppers see, click and buy. Your storefront reports those actions to one endpoint, `POST /v4/{merchant}/events`. Search ranking, recommendations and the analytics in your Depict account all depend on these events, so send them from the first day.

## Request

The body is NDJSON, which is one JSON object on each line. Each line is one event. Send it with `Content-Type: application/x-ndjson`.

```bash theme={null}
curl -s -X POST "https://api.depict.ai/v4/acme/events" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @events.ndjson
```

A body with an impression, a click and an add-to-cart looks like this:

```json theme={null}
{"event_id": "e-1", "type": "impression", "market": "se", "session_id": "b7c1e2", "ts": "2026-11-17T15:04:05Z", "tracking_id": "..."}
{"event_id": "e-2", "type": "click", "market": "se", "session_id": "b7c1e2", "ts": "2026-11-17T15:04:09Z", "tracking_id": "..."}
{"event_id": "e-3", "type": "add_to_cart", "market": "se", "session_id": "b7c1e2", "ts": "2026-11-17T15:04:30Z", "tracking_id": "...", "product_id": "V-1001-BLK-XL"}
```

You can send one event in a request or many. The endpoint takes only POST, and blank lines are skipped.

## Event types

| `type` | Send it when |
| - | - |
| `impression` | A product card becomes visible to the shopper |
| `click` | The shopper clicks a product card |
| `add_to_cart` | The shopper adds a product to the cart |
| `product_view` | The shopper opens a product page |
| `purchase` | The shopper completes an order |

## Fields

Every event has these fields.

| Field | Required | Notes |
| - | - | - |
| `event_id` | yes | An id you create for the event, at most 128 characters. It is for your own use. Depict does not remove duplicates by it |
| `type` | yes | One of the [event types](#event-types) |
| `market` | yes | The shopper's market, as you send it on other requests |
| `session_id` | yes | The shopper's device id, at most 256 characters. See [Session id](#session-id) |
| `ts` | yes | When the action happened, as an ISO 8601 time with an offset, such as `2026-11-17T15:04:05Z`. Depict records the time the event is received |
| `locale` | no | The shopper's locale, such as `sv-SE` |
| `tracking_id` | on `impression` and `click` | The card's `tracking_id`, unchanged. See [Tracking id](#tracking-id) |
| `product_id` | no | On `add_to_cart` and `product_view`, the variant the shopper acted on. See [Product id](#product-id) |
| `query` | no | The search text the card was served for, at most 512 characters |
| `ab_variant` | no | The name of your own A/B test group for the shopper, at most 64 characters |
| `url` | no | The page's URL |
| `referrer` | no | The page's referrer. Used on `product_view` |
| `purchase` | on `purchase` only | The order. See [Purchases](#purchases) |

### Tracking id

Every product card in a search, listing or recommendations response has a `tracking_id`. Send it back unchanged on the card's `impression` and `click` events. It ties the event to the response the card came from and to the card's position in it, so you send no other result id.

Send it on `add_to_cart` and `product_view` too when the shopper came from a card.

Cards from [`products`](https://docs.depict.ai/api-v4/endpoints#products) also have a `tracking_id`, but impressions and clicks on them are not recorded.

### Product id

On `add_to_cart` and `product_view`, an event with a `tracking_id` counts for the card's selected variant. Send `product_id` only when the shopper acted on another variant, such as another size. Without a `tracking_id`, send `product_id`.

On `impression` and `click`, the product always comes from the `tracking_id`.

### Session id

`session_id` is a stable id for the shopper's device that stays the same across visits. It is not an id for one visit. Create it once, store it on the device, and send the same value on every event.

Depict uses it to connect a cart or a purchase to the clicks that came before it. If the id changes between visits, those connections are lost.

### Purchases

A `purchase` event has a `purchase` object. Send one event for each order, for every order in your store, including orders that never touched a Depict result.

```json theme={null}
{"event_id": "e-9", "type": "purchase", "market": "se", "session_id": "b7c1e2", "ts": "2026-11-17T15:20:00Z", "purchase": {"transaction_id": "ORDER-5512", "currency": "SEK", "items": [{"sku": "1001-BLK-XL", "price": 2199, "quantity": 1}]}}
```

| Field | Required | Notes |
| - | - | - |
| `transaction_id` | yes | The order's id in your system |
| `currency` | yes | The ISO 4217 code of the prices, such as `SEK` |
| `items` | yes | One entry for each order line |
| `items[].sku` | yes | The product's transaction product id in your product data. By default that is its SKU. It can't be empty |
| `items[].price` | yes | The price of one unit |
| `items[].quantity` | yes | A whole number, at least 1 |
| `items[].product_id` | no | The variant's `product_id` |

## Response

```json theme={null}
{
  "request_id": "...",
  "accepted": 3,
  "rejected": 0
}
```

* `accepted` is the number of lines that were valid events. A valid event is not always stored. Depict filters out some traffic, such as known crawlers.
* `rejected` is the number of lines that were not valid, such as broken JSON, a missing required field or a line that is too long. Rejected lines are not stored. The valid lines in the same body still count.

The status is `200` even when lines are rejected, so check `rejected` while you build your integration.

## Limits

* A body can be at most 1 MiB. A larger body gets `400 bad_request` and none of its events are stored. Split it into smaller bodies and send them again.
* A line can be at most 64 KiB. A longer line is rejected.

## Send each action once

If your storefront already sends events to Depict's older tracking endpoints, or through a Depict tracking script, don't send the same actions here as well. They would be counted twice. See [Upgrade from v3/v2](https://docs.depict.ai/api-v4/upgrade.md#tracking).

## Requests no shopper sees

The `track: false` header belongs on requests for product data, as [Tracking](https://docs.depict.ai/api-v4/introduction.md#tracking) describes. For tests and server-side checks, don't send events at all.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.