Version 2023.07 of the Criteo retail media API is live as of July18th, 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 ReleaseThe 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.
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}
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 applies 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 |
NOTEWhile 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 -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"
}
}
}'
import requests
import json
url = "https://api.criteo.com/2023-07/retail-media/reports/campaigns"
payload = json.dumps({
"data": {
"type": "RetailMediaReportRequest",
"attributes": {
"id": "1285",
"metrics": [
"impressions"
],
"dimensions": [
"date"
],
"reportType": "summary",
"startDate": "2022-06-06",
"endDate": "2022-07-04",
"timeZone": "America/New_York",
"campaignType": "sponsoredProducts",
"salesChannel": "offline"
}
}
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"data\": {\n \"type\": \"RetailMediaReportRequest\",\n \"attributes\": {\n \"id\": \"8343086999167541140\",\n \"metrics\": [\n \t\t\t\t\t\t\t\t \"impressions\"\n \t\t\t\t\t\t\t\t ],\n \t\t\t\t\t\t \"dimensions\": [\n \t\t\t\t\t\t \"date\"\n \t\t\t\t\t\t\t\t ],\n \"reportType\": \"summary\",\n \"startDate\": \"2020-04-06\",\n \"endDate\": \"2020-06-04\",\n \"timeZone\": \"America/New_York\",\n \"campaignType\": \"sponsoredProducts\",\n \t\t\t\t\t\t \"salesChannel\": \"offline\"\n }\n }\n }");
Request request = new Request.Builder()
.url("https://api.criteo.com/2023-07/retail-media/reports/campaigns")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
.build();
Response response = client.newCall(request).execute();
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2023-07/retail-media/reports/campaigns');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{\n \"data\": {\n \"type\": \"RetailMediaReportRequest\",\n \"attributes\": {\n \"id\": \"8343086999167541140\",\n \"metrics\": [\n \t\t\t\t\t\t\t\t \"impressions\"\n \t\t\t\t\t\t\t\t ],\n \t\t\t\t\t\t \"dimensions\": [\n \t\t\t\t\t\t \"date\"\n \t\t\t\t\t\t\t\t ],\n \"reportType\": \"summary\",\n \"startDate\": \"2020-04-06\",\n \"endDate\": \"2020-06-04\",\n \"timeZone\": \"America/New_York\",\n \"campaignType\": \"sponsoredProducts\",\n \t\t\t\t\t\t \"salesChannel\": \"offline\"\n }\n }\n }');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
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": []
}
[
{
"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
}
]
[
{
"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
}
]
