Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Version 2025.04 of the Criteo Retail Media API is live as of April 22nd, 2025 and will be supported until April 28th, 2026. A new Postman collection for 2025.04 is also available in the Criteo Postman workspace.

New SDK Release A new SDK version will be available for the 2025.04 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. The changes of versions 2025.04 are:

• a new base URL,
• updated Terms & Conditions
• a new endpoint for Private Market Child Accounts,
• a new Seller Search endpoint for Marketplace seller accounts,
• a new endpoint for CPC Min Bid
• new metrics within the analytics endpoints,
• removal of older keyword endpoints to provide a clearer path toward the comprehensive keyword endpoints

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/2025-01/retail-media/{endpoint}

to the new base URL:

https://api.criteo.com/2025-04/retail-media/{endpoint}

What’s New

Updated Terms & Conditions

We’ve introduced an updated Terms & Conditions page, which focuses on the below key areas:

• Agreement Scope: The terms apply to the use of Criteo’s APIs and are complementary to any main agreements with Criteo or its affiliates.
• Acceptance: Users must accept these terms to access and use the APIs, and corporate entities must ensure authorized personnel accept on their behalf.
• Definitions: Important terms such as “Affiliate,” “API Terms,” “Applicable Laws,” “Criteo Materials,” and “Data Protection Laws” are clearly defined.
• Compliance: Users must comply with technical requirements and specifications provided by Criteo.
• Supplemental Terms: Depending on API usage, additional terms and conditions may be required.

You can find the new Terms & Conditions here.

Private Market Child Accounts

In version 2025.04, we’ve introduced a new endpoint that is used to view all private market child accounts within a private market retailer account. By calling this endpoint, retailers can retrieve information about all child accounts associated with their given accountId.

Updated Endpoints

The following new catalog endpoint can be found below:

Sample Response

For Private Market Child Accounts:

{
    "metadata": {
        "count": 4,
        "offset": 0,
        "limit": 25
    },
    "data": [
        {
            "id": "680xxxxxxxxxxxxxxxx",
            "type": "RetailMediaChildAccount",
            "attributes": {
                "name": "test 1",
                "companyName": "test 1",
                "onBehalfCompanyName": "test 1",
                "type": "Demand",
                "subType": "Brand",
                "countryIds": [
                    "US"
                ],
                "currencyId": "USD",
                "timeZone": "UTC"
            }
        },
        {
            "id": "680xxxxxxxxxxxxxxxx",
            "type": "RetailMediaChildAccount",
            "attributes": {
                "name": "test 2",
                "companyName": "test 2",
                "onBehalfCompanyName": "test 2",
                "type": "Demand",
                "subType": "Brand",
                "countryIds": [
                    "US"
                ],
                "currencyId": "USD",
                "timeZone": "UTC"
            }
        },
        {
            "id": "680xxxxxxxxxxxxxxxx",
            "type": "RetailMediaChildAccount",
            "attributes": {
                "name": "test 3",
                "companyName": "test 3",
                "onBehalfCompanyName": "test 3",
                "type": "Demand",
                "subType": "Brand",
                "countryIds": [
                    "US"
                ],
                "currencyId": "USD",
                "timeZone": "UTC"
            }
        },
        {
            "id": "700xxxxxxxxxxxxxxxx",
            "type": "RetailMediaChildAccount",
            "attributes": {
                "name": "test 4",
                "companyName": "test 4",
                "onBehalfCompanyName": "test 4",
                "type": "Demand",
                "subType": "Seller",
                "countryIds": [
                    "US"
                ],
                "currencyId": "USD",
                "timeZone": "UTC"
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Seller Search

In version 2025.04, we’ve introduced a new marketplace seller search endpoint that is focused on providing a programmatic way to identify all marketplace sellers (and, consequently, retailers) associated with the respective account. This endpoint enables the ability for users to leverage the appropriate information to support campaign activations.

Updated Endpoints Includes

The following new catalog endpoint can be found below:

Sample Request

For Seller Search:

curl --location 'https://api.criteo.com/2025-04/retail-media/accounts/sellers/search' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer ****' \
--data '{
  "data": {
    "attributes": {
      "accountIds": [
        "667xxxxxxxxxxxxxxxx",
        "524xxxxxxxxxxxxxxxx"
      ],
      "includeDetails": true
    },
    "type": "SellerSearch"
  }
}'

Sample Response

For Seller Search:

{
    "data": [
        {
            "type": "SellerSearchResult",
            "attributes": {
                "accountId": "667xxxxxxxxxxxxxxxx",
                "sellers": [
                    {
                        "sellerId": "5e0xxxxxxxxxxxxxxxx",
                        "retailerId": 1234,
                        "name": "Seller1"
                    }
                ]
            }
        },
        {
            "type": "SellerSearchResult",
            "attributes": {
                "accountId": "524xxxxxxxxxxxxxxxx",
                "sellers": [
                    {
                        "sellerId": "1xxxxxxxx",
                        "retailerId": 123,
                        "name": "Seller2"
                    }
                ]
            }
        }
    ],
    "warnings": [],
    "errors": []
}

CPC Min Bid

In version 2025.04, we’ve introduced a new CPC Min Bid endpoint that is focused on providing a cleaner way to identify what the minimum bid will be when a selection of Sponsored Products are used for the intention of adding them to a line item. Line items have bid settings, and in order to set the right one, you will need to know what the minimum bid is for your products, as well as the highest minimum bid, because the highest one will be the minimum for your line item.

Updated Endpoints Includes

The following new catalog endpoint can be found below:

Sample Request

For CPC Min Bids:

curl --location 'https://api.criteo.com/2025-04/retail-media/retailers/{retailerId}/cpc-min-bids' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer ****' \
--data '{
  "data": {
    "attributes": {
      "skuIds": [
        "a1b2c3",
        "d4e5f6",
        "g7h8i9"
      ]
    },
    "type": "CpcMinBidsRequest"
  }
}'

Sample Response

For CPC Min Bids:

{
    "data": {
        "type": "CpcMinBidsResponse",
        "attributes": {
            "overallMinBid": 0.5000,
            "skuMinBids": [
                {
                    "skuId": "a1b2c3",
                    "minBid": 0.3500
                },
                {
                    "skuId": "d4e5f6",
                    "minBid": 0.4500
                },
                {
                    "skuId": "g7h8i9",
                    "minBid": 0.5000
                }
            ]
        }
    },
    "warnings": [],
    "errors": []
}

New Metrics

In version 2025.04, we’ve introduced new metrics within the analytics endpoints. The updated analytics endpoints provide users with deeper, more comprehensive insights, enabling them to explore data more effectively. Additionally, the introduction of new report types empowers users to make more informed, data-driven decisions by offering tailored, actionable insights that better align with your strategic goals. In the latest version, you now have the flexibility to generate metrics with a focus on win rate to allow users to more precisely measure auction success rates. The win rate metric is only available to Sponsored Products via the DSP API today and is defined as the number of SKU slots that won at the auction divided by the number of SKUs that participated in the auction. There are also new metrics with a focus on video designed to provide deeper insights into our performance and impact. These metrics are available in flexible reporting only and can be accessed via line-item reporting only via the DSP API. These metrics are also available via the SSP API.

Updated Endpoints Includes

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

It should be noted that when you call for the winRate metric, you will be required to either call for the campaignType object and filter to sponsoredProducts or include the campaignTypeName dimension. This is due to the calculation for Sponsored Product & Onsite Display being different. As a result, it will be important as it relates to efficient reporting to include this object or dimension when calling for the metric. Omitting either of these when calling for the winRate metric will result in an error.

Sample Request for Win Rate without campaignType Object

For Campaign Report:

curl --location 'https://api.criteo.com/2025-04/retail-media/reports/campaigns' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer ****' \
--data '{
  "data": {
    "attributes": {
      "endDate": "2025-04-22",
      "startDate": "2025-04-01",
      "campaignType": "all",
      "clickAttributionWindow": "none",
      "dimensions": [
        "campaignName",
        "campaignId"
      ],
      "format": "csv",
      "id": "1234",
      "metrics": [
        "impressions",
        "clicks",
        "winRate"
      ],
      "reportType": "summary",
      "salesChannel": "all",
      "timezone": "UTC",
      "viewAttributionWindow": "none"
    },
    "type": "AsyncCampaignsReportRequest"
  }
}'

Sample Response for Win Rate without campaignType Object

For 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.

{
    "warnings": [],
    "errors": [
        {
            "traceId": "0ec574b04465214f64431be3d5321954",
            "traceIdentifier": "0ec574b04465214f64431be3d5321954",
            "type": "validation",
            "code": "win-rate-metric-not-allowed",
            "instance": "/v2/reports/async/line-items",
            "title": "WinRate metric is only supported for SponsoredProducts campaigns.",
            "detail": "Please provide either the 'campaignTypeName' in dimensions or filter on SponsoredProducts using the 'campaignType' filter."
        }
    ]
}

Sample Request for Win Rate with campaignType Object

For Campaign Report:

curl --location 'https://api.criteo.com/2025-04/retail-media/reports/campaigns' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer ****' \
--data '{
  "data": {
    "attributes": {
      "endDate": "2025-04-22",
      "startDate": "2025-04-01",
      "campaignType": "sponsoredProducts",
      "clickAttributionWindow": "none",
      "dimensions": [
        "campaignName",
        "campaignId"
      ],
      "format": "csv",
      "id": "1234",
      "metrics": [
        "impressions",
        "clicks",
        "winRate"
      ],
      "reportType": "summary",
      "salesChannel": "all",
      "timezone": "UTC",
      "viewAttributionWindow": "none"
    },
    "type": "AsyncCampaignsReportRequest"
  }
}'

Sample Response for Win Rate with campaignType Object

{
    "data": {
        "attributes": {
            "status": "pending",
            "rowCount": 0,
            "fileSizeBytes": 0,
            "md5CheckSum": null,
            "createdAt": "2025-04-18T18:47:24.162Z",
            "expiresAt": null,
            "message": null,
            "id": "f4c73ba1-9a9e-447b-8c31-1baf81e1c957"
        },
        "id": "f4c73ba1-9a9e-447b-8c31-1baf81e1c957",
        "type": "StatusResponse"
    },
    "warnings": [
        {
            "type": "validation",
            "code": "ignored-report-type",
            "title": "Report Type has been ignored",
            "detail": "Report Type has been ignored because Dimensions and Metrics have been provided. Please remove them if you want to use one of the templates."
        },
        {
            "type": "validation",
            "code": "ignored-win-rate-metric",
            "title": "WinRate metric is only supported for SponsoredProducts campaigns.",
            "detail": "WinRate will be null for OnSiteDisplays campaigns."
        }
    ],
    "errors": []
}

New metrics

Update to Keyword Endpoints

In version 2025.04, we will be removing some older versions of our keyword endpoints to better guide users towards a comprehensive keyword targeting experience. A selection of endpoints are excluded from 2025.04 because they currently support only negative keyword targeting. The endpoints that are inclusive of both negative keyword targeting and positive keyword targeting already exist, and should be leveraged going forward for keyword targeting purposes. See below for the impacted endpoints: Endpoints to be removed:

Endpoints to use instead: