GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Recommended Categories

Suggest Edits

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

MethodEndpointDescription
POST/preview/retail-media/retailers/{retailerId}/recommend-categoriesGets the top 50 recommended categories for specified products

Attributes table

AttributeData TypeDescription
retailerId stringUnique identifier for the retailer. Found using the GET retailers endpoint.
Required in URL path.
Writable? N / Nullable? N
productIdsarrayArray 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

CodeMeaningTroubleshooting Hint
🟢 200SuccessRequest processed successfully, returns up to 50 recommended categories.
🔴 400Bad RequestCheck that productIds array is provided with 1-1000 items, and retailerId is valid in URL path.
🔴 403ForbiddenVerify 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