> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.postman.com/realcriteo/workspace/criteo/overview).

<Info>
  **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.
</Info>

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***

```text theme={null}
https://api.criteo.com/2023-04/retail-media/{endpoint}
```

to

***New base URL***

```text theme={null}
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

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/campaigns
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a Campaign Report Request
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/line-items
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a Line Item Report Request
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

### 🌟 New report types

<table>
  <thead>
    <tr>
      <th>
        <p>
          Report Type
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Served Category
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          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
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Environment
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Daily metrics segmented by the environment (desktop, mobile, app) in which the ad interaction takes place
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

### 🌟 New report filters

<table>
  <thead>
    <tr>
      <th>
        <p>
          Key-Value Pairs
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Metrics
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Ability to filter by the accepted metrics:

          <code>
            impressions, clicks, spend, attributedSales, attributedUnits, attributedOrders, ctr, cpc, cpo, cpm, roas, uniqueVisitors, frequency, assistedUnits, assistedSales
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Dimensions
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Ability to filter by the accepted dimensions:

          <code>
            date, campaignId, campaignName, campaignTypeName, advProductCategory, advProductId, advProductName, brandId, brandName, pageTypeName, keyword, salesChannel, retailerId, retailerName
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Campaign Type
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Ability to filter by the accepted values:

          <code>
            sponsoredProducts, onSiteDisplays
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Sales Channel
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Ability to filter by the accepted values:

          <code>
            offline, online
          </code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Info>
  **NOTE**

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

***

**Sample Request** - *Campaign Report*

<CodeGroup>
  ```bash cURL theme={null}
  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"
  		}
  	}
  }'
  ```

  ```python Python expandable theme={null}
  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)
  ```

  ```java Java theme={null}
  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 PHP theme={null}
  <?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();
  }
  ```
</CodeGroup>

**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

```json theme={null}
{
    "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

```text theme={null}
[
    {
        "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

```text theme={null}
[
    {
        "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
    }
]
```