GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
added

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 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 applies for both the asynchronous campaign and line-item endpoints for report generation

VerbEndpointDescription
POST/reports/campaignsCreate a Campaign Report Request
POST/reports/line-itemsCreate a Line Item Report Request

:star2: NEW REPORT TYPES

Report TypeData TypeDescription
Served CategorystringDaily 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
EnvironmentstringDaily metrics segmented by the environment (desktop, mobile, app) in which the ad interaction takes place

:star2: NEW REPORT FILTERS

Key-Value PairsData TypeDescription
MetricsstringAbility to filter by the accepted metrics: impressions, clicks, spend, attributedSales, attributedUnits, attributedOrders, ctr, cpc, cpo, cpm, roas, uniqueVisitors, frequency, assistedUnits, assistedSales
DimensionsstringAbility to filter by the accepted dimensions: date, campaignId, campaignName, campaignTypeName, advProductCategory, advProductId, advProductName, brandId, brandName, pageTypeName, keyword, salesChannel, retailerId, retailerName
Campaign TypestringAbility to filter by the accepted values: sponsoredProducts, onSiteDisplays
Sales ChannelstringAbility 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 -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
    }
]