Version 2023.07 Release Notes

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.

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 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();
}

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

2026

2025

2023

2022

2021

2020

Version 2023.07 Release Notes

New Base URL

What’s new

Analytics Report Types & Custom Filters

🌟 New report types

🌟 New report filters

​New Base URL

​What’s new

​Analytics Report Types & Custom Filters

​🌟 New report types

​🌟 New report filters

New Base URL

What’s new

Analytics Report Types & Custom Filters

🌟 New report types

🌟 New report filters