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.

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

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

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. 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 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."
        }
    ]
}

Introduction

Guides for Retail Media API

Recommended Categories

Introduction

Endpoint

Attributes table

Get Recommended Categories

Responses

Common Error Scenarios

What’s next

​Introduction

​Endpoint

​Attributes table

​Get Recommended Categories

​Responses

​Common Error Scenarios

​What’s next

Introduction

Endpoint

Attributes table

Get Recommended Categories

Responses

Common Error Scenarios

What’s next