Version 2025.01 Release Notes - Criteo Docs

Version 2025.01 Release Notes

Version 2025.01 of the Criteo retail media API is live as of January 21st, 2025 and will be supported until January 27th, 2026. A new Postman collection for 2025.01 is also available in the Criteo Postman workspace.

New SDK Release A new SDK version will be available for the 2025.01 release.

This version introduces new capabilities to Criteo Retail Media API and changes to existing endpoints. This page aims at listing all changes that happened endpoint per endpoint. Only endpoints with changes are listed here. The changes of versions 2025.01 are:

a new base URL,
a new endpoint for Recommended Keywords,
a new catalog endpoint for Marketplace sellers,
new metrics and a new type of report within the analytics endpoints,
a new consent granting endpoint.

New Base URL

With the introduction of this new version, the base URL will now change from the old base URL:

https://api.criteo.com/2024-10/retail-media/{endpoint}

to the new base URL:

https://api.criteo.com/2025-01/retail-media/{endpoint}

What’s New

Recommended Keywords

In version 2025.01, we’ve introduced a new recommended keywords’ endpoint that is focused on providing users with the ability to see keywords that are automatically recommended by our keyword model for a given line item. A line item can have multiple products in it, and only the top 100 keywords will be returned. A user can use this endpoint for Sponsored Products and Onsite Display buy types and can also expect to see keywords recommended by our keyword model and keywords that are automatically approved and/or rejected when submitted at the line item level.

Updated Endpoints

The following new catalog endpoint can be found below:

Verb	Endpoint	Description
GET	`line-items/{lineItemId}/keywords/recommended`	Get Recommended Keywords for a Line Item

Sample Response

For Recommended Keywords:

{
    "data": {
        "type": "RecommendedKeywords",
        "attributes": {
            "keywords": {
                "humidifier": {
                    "reviewState": "Recommended",
                    "matchType": "PositiveExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [],
                        "positiveExact": [
                            "humidifier",
                            "humidifier and",
                            "humidifier#"
                        ]
                    },
                    "createdAt": "0001-01-01T00:00:00",
                    "updatedAt": "0001-01-01T00:00:00"
                },
                // More keywords...
            },
            "recommendedKeywords": [
                "311i max",
                "air cleaner",
                // More recommended keywords...
            ]
        }
    },
    "warnings": [],
    "errors": []
}

Catalog for Marketplace Sellers

In version 2025.01, we’ve introduced a new catalog endpoint that is focused on making catalog requests for marketplace seller SKUs. Marketplace seller SKUs are sourced from marketplace brands that are unique because they allow for third-party suppliers to promote their products on retailer inventory.

Updated Endpoints Includes

The following new catalog endpoint can be found below:

Verb	Endpoint	Description
POST	`/accounts/{accountId}/catalogs/sellers`	Create a Seller Catalog Request

Sample Request

For Seller Catalog:

curl --location 'https://api.criteo.com/2025-01/retail-media/accounts/{accountId}/catalogs/sellers' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer xxxx' \
--data '{\n  "data": {\n    "type": "RetailMediaCatalog",\n    "attributes": {\n      "sellers": [\n        {\n          "retailerId": "{retailerId}",\n          "sellerId": "{sellerId}"\n        }\n      ]\n    }\n  }\n}'

Sample Response

For Seller Catalog: Generating a seller catalog will return an id.

{
    "data": {
        "id": "670751679281950720",
        "type": "RetailMediaCatalogStatus",
        "attributes": {
            "status": "pending",
            "currency": null,
            "rowCount": null,
            "fileSizeBytes": null,
            "md5Checksum": null,
            "createdAt": "2025-01-24T22:07:42.35+00:00",
            "message": null
        }
    }
}

New Metrics & Report Type

In version 2025.01, we’ve introduced new metrics as well as a new report type within the analytics endpoints. The updated analytics endpoints provide users with deeper insights, enabling them to explore data more effectively. Additionally, the introduction of new report types empowers users to make more informed, data-driven decisions.

Updated Endpoints Includes

Verb	Endpoint	Description
POST	`/reports/campaigns`	Create a Campaign Report Request
POST	`/reports/line-items`	Create a Line Item Report Request

Sample Request

For Campaign Report:

curl --location 'https://api.criteo.com/2025-01/retail-media/reports/campaigns' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer xxxx' \
--data '{\n  "data": {\n    "type": "RetailMediaReporting",\n    "attributes": {\n      "endDate": "2025-01-15",\n      "startDate": "2025-01-01",\n      "id": "{campaignId}",\n      "campaignType": "all",\n      "salesChannel": "all",\n      "format": "csv",\n      "reportType": "capout",\n      "clickAttributionWindow": "30D",\n      "viewAttributionWindow": "1D",\n      "timezone": "UTC"\n    }\n  }\n}'

Sample Response

For Both: Generating a campaign and line-item report will generate a reportId.

{
    "data": {
        "attributes": {
            "status": "pending",
            "rowCount": 0,
            "fileSizeBytes": 0,
            "md5CheckSum": null,
            "createdAt": "2025-01-24T22:23:37.437Z",
            "expiresAt": null,
            "message": null,
            "id": "fc0343ed-62d9-4295-9d32-b1c13f4516a1"
        },
        "id": "fc0343ed-62d9-4295-9d32-b1c13f4516a1",
        "type": "StatusResponse"
    },
    "warnings": [{
        "type": "validation",
        "code": "ignored-dimensions-and-metrics-and-timezone",
        "title": "Dimensions and Metrics and TimeZone have been ignored",
        "detail": "Dimensions, Metrics, TimeZone and Attribution Window have been ignored because they are not supported for the 'capout' Report Type. TimeZone is default to timezone used by account. Attribution Window is default to attribution set at campaign level."
    }],
    "errors": []
}

New Consent Granting endpoint

In version 2025.01, we’ve introduced a new consent granting endpoint that is specifically designed to support the Authorization Code workflow.

Updated Endpoints Includes

The following new catalog endpoint can be found below:

Verb	Endpoint	Description
POST	`/accounts/{accountId}/grant-consent`	Grant Consent to the Business Application