Recommended Categories
Introduction
The Recommended Categories endpoint helps you discover the most relevant product categories for your advertising campaigns by leveraging a retailer's taxonomy structure. This endpoint analyzes your specified products and returns up to 50 recommended categories that align with where your products naturally fit within the retailer's inventory organization.
Recommended categories are pulled directly from the retailer's taxonomy, with each product having a category that indicates its position within the retailer's inventory hierarchy. The endpoint uses the pages and child pages where products are already positioned to generate recommendations, ensuring that the suggestions are inherently relevant to the products associated with your line items.
This data-driven approach is particularly valuable for campaign targeting optimization, category expansion strategies, and understanding how your products align with the retailer's organizational structure. By using these recommendations, you can improve campaign performance by targeting the most appropriate product categories and reaching shoppers who are browsing relevant product sections.
Endpoints
Method | Endpoint | Description |
---|---|---|
POST | /preview/retail-media/retailers/{retailerId}/recommend-categories | Gets the top 50 recommended categories for specified products |
Attributes table
Attribute | Data Type | Description |
---|---|---|
retailerId | string | Unique identifier for the retailer. Found using the GET retailers endpoint. Required in URL path. Writable? N / Nullable? N |
productIds | array | Array of product ID strings for category recommendations. Min: 1 item, Max: 1000 items. Required field. Writable? Y / Nullable? N |
Field Definitions
- Writeable (Y/N): Indicates if the field can be modified in requests.
- Nullable (Y/N): Indicates if the field can accept null/empty values.
- Primary Key: The main identifier field required for the endpoint to function correctly. Primary keys are typically ID fields (e.g.,
retailerId
,campaignId
,lineItemId
) and are usually required in the URL path.
Get Recommended Categories
This endpoint retrieves the top 50 recommended categories for specified products based on the retailer's taxonomy structure. Categories are determined by the pages and child pages where products are currently positioned within the retailer's inventory.

https://api.criteo.com/preview/retail-media/retailers/{retailerId}/recommend-categories
Sample Request
curl -L -X POST 'https://api.criteo.com/preview/retail-media/retailers/12345/recommend-categories' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
"data": {
"attributes": {
"productIds": [
"PROD123",
"PROD456",
"PROD789"
]
},
"type": "RecommendedCategoriesRequestV1"
}
}'
Sample Response
{
"data": [
{
"id": "520020",
"type": "CategoryV1",
"attributes": {
"text": "Electronics|Audio|Headphones|Wireless",
"name": "Wireless Headphones",
"parentId": "522931"
}
},
{
"id": "810902",
"type": "CategoryV1",
"attributes": {
"text": "Electronics|Audio|Headphones",
"name": "Headphones",
"parentId": "2816897"
}
},
{
"id": "2802692",
"type": "CategoryV1",
"attributes": {
"text": "Electronics|Audio",
"name": "Audio Equipment",
"parentId": "13772216"
}
}
],
"warnings": [
{
"traceId": "7eaa128c7ef3417ddb40654d40006773",
"type": "validation",
"code": "not-all-skus-available",
"title": "Partial result",
"detail": "Sku ids 8110729593111,8110728872215 are not available."
}
],
"errors": []
}
Responses
Code | Meaning | Troubleshooting Hint |
---|---|---|
🟢 200 | Success | Request processed successfully, returns up to 50 recommended categories. |
🔴 400 | Bad Request | Check that productIds array is provided with 1-1000 items, and retailerId is valid in URL path. |
🔴 403 | Forbidden | Verify authorization and retailer access permissions. |
Common Error Scenarios
Missing or Empty Product IDs
{
"warnings": [],
"errors": [
{
"traceId": "6f7fcf70d8b024627481b771c79656f6",
"type": "validation",
"code": "model-validation-error",
"title": "Model validation error",
"detail": "Required property 'skuIds' not found in JSON. Path 'data.attributes', line 7, position 5."
}
]
}
Invalid Retailer ID
{
"warnings": [],
"errors": [
{
"traceId": "ea6343210d0922cd1217b99448e98839",
"type": "validation",
"code": "model-validation-error",
"title": "Model validation error",
"detail": "The value ':retailerId' is not valid."
}
]
}
Updated about 8 hours ago