Skip to main content

Definition

A product details page (PDP) shows the details of a single product or multiple products under the same parent ID. For a PDP (viewItem) request, send at least one of item or parent-item. Send item whenever the viewed SKU is known; parent-item can supplement it or serve as a fallback.

Parameters

event-type

Value: viewItem Description: Indicates to the API that this is a PDP request. Required: Yes

page-id

Description: An identifier that tells Criteo which placements to return (if any) for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type:
  • In Americas: Typically follows the structure [event-type]_API_[environment], e.g., viewItem_API_desktop, viewItem_API_mobile, viewItem_API_iOS, viewItem_API_android.
  • In EMEA: Typically follows the structure [event-type]Api[environment], e.g., viewItemApiDesktop, viewItemApiMobile, viewItemApiAios, viewItemApiAa.
Required: Yes

item

Description: SKU IDs corresponding to the product(s) on the PDP. To send multiple products, separate values with a pipe (|). The order of values must match the order used in price and availability. Example (single product): 123-ab Example (multiple products): 123-ab|456-cd|789-ef Required: At least one of item or parent-item is required. item is recommended for SKU-level detail.

parent-item

Description: Parent SKU ID for the product on the PDP. It should match the item_group_id in the product feed. This parameter is accepted in place of item or can be sent alongside it. Example: 123 Required: Required if item is omitted; otherwise recommended when the eCommerce platform uses parent items.

price

Description: Current price of the product (with discount, if any). When sending multiple products, provide one price per product separated by a pipe (|), in the same order as item. Price is still required when using parent-item instead of item. Example (single product): 34.99 Example (multiple products): 34.99|42.21|38.99 Required: Yes

availability

Description: Stock status of the product. Send 1 if in stock, 0 if out of stock. When sending multiple products, provide one value per product separated by a pipe (|), in the same order as item. Availability is still required when using parent-item instead of item. Example (single product): 1 Example (multiple products): 1|0|1 Required: Yes

category

Description: For PDP calls, this parameter passes an explicit category used for both ad-serving and Served Category reporting. If this field is not present, Criteo will default to the primary taxonomy of the SKU passed in the item parameter. If passed, this value should match the product_type_key value in the product feed. See more details here. When sending only parent-item, include category if available. The taxonomy fallback described above relies on an item SKU.
Without this parameter, all PDP ad activity is grouped under Page Without Category in UI reporting. While ad-serving still works, Served Category reporting will not reflect the actual page categories for PDPs.
Examples:
  • Category ID, full breadcrumb style: 123>4567>89012
  • Category ID, end-node-only style: 89012
  • Category name style: Computing>Keyboards and Mice>Mice
Best Practices:
  • Category ID is preferred over category name to avoid issues with typos, punctuation, and accented letters (especially in non-English languages).
  • If opting for category name:
    • The category name is case-insensitive.
    • Spaces between the separator (>) are ignored.
Required: No

Choosing item and parent-item

Send item to identify the exact SKU viewed. You can also send parent-item to identify its parent group. If only the parent ID is available, a request with parent-item, price, and availability is accepted as PDP traffic and still contributes to product keyword modeling using the parent ID. A parent-only request has less product detail:
  • It identifies the parent group, not the exact variant viewed.
  • Product name, taxonomy, and brand enrichment may be unavailable unless the parent ID also resolves in the product catalog.
  • The page-view beacon does not receive a brand ID from parent-item alone.
  • Real-time price and availability updates cannot be tied to a specific SKU.
Prefer item when the exact SKU is known. Use parent-item as a supplement or fallback.

Sample Calls

The header values in the sample calls are illustrative. Make sure to replace them with the appropriate values for your implementation.

AMER


EMEA


Parent-only fallback

If the viewed SKU is unavailable, send its parent ID in parent-item with the required price and availability. The request does not need an item value.

Multiple products

When a PDP displays several products under the same parent, send all items in a single call using pipe-separated values. The position of each value in item, price, and availability must correspond to the same product.

Mock retailer API response

The API call below will return a response for a mock retailer.
You can see an example of the response here.



What’s next