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

# Which ID goes where

> Tracking uses three different kinds of ids. Sending the right one in each event is what makes attribution work.

Depict tracking uses **three id vocabularies**. They look similar but are not interchangeable, and sending the wrong kind does not produce an error — the event is accepted and then silently fails to match anything, which quietly degrades your metrics. This page is the reference for which id each event needs.

| Event | Id to send | Where it comes from |
| - | - | - |
| Product card clicks | **result id** (`search_result_id`, `recommendation_id` or `product_listing_result_id`) | Returned inside every display in our API responses. You place it on the card as a data attribute — see [Product Card Tracking](/api-guide/tracking/product-cards). |
| `setProductId` (PDP views) | **product id** (`product_id`) | The `product_id` field of the displays our API returns. It identifies the product on variant level — on Shopify this is the variant id. |
| `addToCart` | **product id** (`product_id`) | Same as `setProductId`. Use the id of the variant that was added. |
| `purchase` → `items[].item_id` | **transaction product id** | The id your product data was ingested with for transaction matching. By default this is the SKU from your catalog; on Shopify it is the variant's SKU, or the variant id for variants without a SKU. |

## Why the difference matters

* **Result ids** are unique per API response, not per product — they tie a click to the exact search, listing or recommendation that produced it. That link is what powers surface-level performance metrics and lets ranking learn from real behaviour.
* **Product ids** join PDP views and add-to-carts to your catalog. If the id you send doesn't match the displays' `product_id`, those events can't be connected to products.
* **Transaction product ids** join purchase line items to your catalog through a mapping that is refreshed on every catalog ingestion. A line item whose `item_id` doesn't match drops out of per-product revenue, best-seller and funnel metrics — while still counting toward raw totals, which makes the gap easy to miss.

<Warning>
  The most common integration mistake is sending the displays' `product_id` as
  a purchase `item_id` (or vice versa). They are different vocabularies —
  purchases match on your SKUs, not on `product_id` — unless your catalog
  happens to use the same value for both.
</Warning>

## Result-id lifetime and event validation

Rules that apply when sending events — DPC follows them automatically, so they matter mostly for server-side or custom event senders posting to `/create-events`:

* **A result id is attributable for 10 minutes** after the API response that contained it was generated. Send click events promptly with the exact id from the clicked display — an event with an expired or unknown result id is accepted with a 200 but can no longer be attributed to its search, listing or recommendation.
* Every event must carry at least one identity field: `session_id`, `user_id` or `dsid`. A batch containing an event without one is rejected with 422, naming the index of the failing event.
* A `click` event must carry at least one of `search_result_id`, `recommendation_id`, `product_listing_result_id` or `click_location` — otherwise the batch is rejected with 422.

Which result id each endpoint returns:

| Endpoint the display came from | Result id on the display |
| - | - |
| `/v3/search/results` | `search_result_id` |
| `/v3/listings/.../products` | `product_listing_result_id` |
| `/v3/recommend/products` | `recommendation_id` |
| `/v3/search/related` | `recommendation_id` — related-products displays are recommendations and do **not** carry `search_result_id` |

## How to verify

The "Tracking status" tab on [app.depict.ai](https://app.depict.ai) shows your incoming events live. The table at the bottom lists examples of valid product ids from your ingested catalog — compare them against what your events are sending. After your first test purchases, confirm they map to catalog products rather than only appearing in raw event counts.


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