Version 2023.07 Release Notes - Criteo Docs

Documentation Index

Fetch the complete documentation index at: /llms.txt

Version 2023.07 of the Criteo retail media API is live as of July 18th, 2023 and will be supported until July 31st, 2024. A new Postman collection for 2023.07 is also available in the Criteo Postman workspace.

New SDK Release The SDK library is undergoing improvements at the moment for retail media and marketing solutions. A new SDK version will not be available for the 2023.07 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.

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/2023-04/retail-media/{endpoint}

to New base URL

https://api.criteo.com/2023-07/retail-media/{endpoint}

What’s new

Analytics Report Types & Custom Filters

In version 2023.07, we’ve introduced two new report types and custom filtering options for the analytics endpoints. The updated analytics API gives you greater control over generating your reports. In the latest version, you now have the flexibility to generate reports using all metrics and dimensions or choose select metrics and dimensions that you want to use. We are also introducing the ability to filter Sales Channel so that users can filter for online or offline sales.

Updated Endpoints Includes The following new reporting changes apply for both the asynchronous campaign and line-item endpoints for report generation

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

🌟 New report types

Report Type Data Type Description
Served Category string Daily metrics segmented by the category of the page on which an ad was served; categories are specific to the retailer, which may differ from standardized categories across brands and retailers
Environment string Daily metrics segmented by the environment (desktop, mobile, app) in which the ad interaction takes place

🌟 New report filters

Key-Value Pairs Data Type Description
Metrics string Ability to filter by the accepted metrics: impressions, clicks, spend, attributedSales, attributedUnits, attributedOrders, ctr, cpc, cpo, cpm, roas, uniqueVisitors, frequency, assistedUnits, assistedSales
Dimensions string Ability to filter by the accepted dimensions: date, campaignId, campaignName, campaignTypeName, advProductCategory, advProductId, advProductName, brandId, brandName, pageTypeName, keyword, salesChannel, retailerId, retailerName
Campaign Type string Ability to filter by the accepted values: sponsoredProducts, onSiteDisplays
Sales Channel string Ability to filter by the accepted values: offline, online

NOTE While you have the ability to filter by the available values, omitting these values and not filtering will render all values comprehensively.

Sample Request - Campaign Report

cURL

curl -L 'https://api.criteo.com/2023-07/retail-media/reports/campaigns' \
-H 'Content-Type: application/json' \
-H 'Accept: text/plain' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
    "data": {
        "type": "Reporting",
        "attributes": {
            "endDate": "2023-04-01",
            "startDate": "2023-03-01",
            "metrics": [\
                "ctr",
                "cpc"\
            ],
            "dimensions": [\
                "date",
                "campaignName",
                    "environment"\
            ],
            "clickAttributionWindow": "7D",
            "viewAttributionWindow": "none",
            "timezone": "America/New_York",
            "campaignType": "sponsoredProducts",
            "salesChannel": "offline",
            "format": "json",
            "reportType": "environment",
            "id": "1374"
        }
    }
}'

Sample Response - _Both Generating a campaign and line-item report will generate a reportId. Once the report is done, use the GET | /retail-media/reports/{reportId}/output to download results

{
    "data": {
        "attributes": {
            "status": "pending",
            "rowCount": 0,
            "fileSizeBytes": 0,
            "md5CheckSum": null,
            "createdAt": "2023-08-10T15:12:48.872Z",
            "expiresAt": null,
            "message": null,
            "id": "d3c658ff-f2b7-47f6-b3dc-d00330b1bb38"
        },
        "id": "d3c658ff-f2b7-47f6-b3dc-d00330b1bb38",
        "type": "StatusResponse"
    },
    "warnings": [\
        {\
            "traceId": null,\
            "traceIdentifier": null,\
            "type": "validation",\
            "code": "ignored-report-type",\
            "instance": null,\
            "title": "Report Type has been ignored",\
            "detail": "Report Type has been ignored since Dimensions and Metrics has been provided. Please remove them if you want to use one of the templates.",\
            "source": null\
        }\
    ],
    "errors": []
}

Example of Environment Report In this example we generate a environment report by specifying only specific dimensions and metrics

[\
    {\
        "campaignName": "Marketing Financials",\
        "pageEnvironmentTypeName": "mobile",\
        "date": "2023-03-09",\
        "ctr": 0.0023,\
        "cpc": 0.3828\
    },\
....\
    {\
        "campaignName": "Marketing Financials",\
        "pageEnvironmentTypeName": "mobile",\
        "date": "2023-03-15",\
        "ctr": 0.0023,\
        "cpc": 0.4080\
    }\
]

Example of Served Category Report In this example we generate a served category report by specifying only specific dimensions and metrics

[\
    {\
        "campaignName": "Marketing Financials",\
        "advProductCategory": "home & garden > decor > wind wheels & spinners",\
        "date": "2023-03-08",\
        "ctr": 0.0026,\
        "cpc": 0.3794\
    },\
...\
    {\
        "campaignName": "Marketing Financials",\
        "advProductCategory": "home & garden > decor > wind wheels & spinners",\
        "date": "2023-03-12",\
        "ctr": 0.0022,\
        "cpc": 0.3796\
    }\
]