Skip to main content
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.
A body with an impression, a click and an add-to-cart looks like this:
You can send one event in a request or many. The endpoint takes only POST, and blank lines are skipped.

Event types

Fields

Every event has these fields.

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

Response

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

Requests no shopper sees

The track: false header belongs on requests for product data, as Tracking describes. For tests and server-side checks, don’t send events at all.