Skip to main content

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

​
Endpoint

Method

Endpoint

Description

POST

/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 theGETretailers 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

*Required
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. Sample Request 
curl -L -X POST 'https://api.criteo.com/{version}/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 thatproductIdsarray is provided with 1-1000 items, andretailerIdis 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."
        }
    ]
}