> ## 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.
# Retail Media API Changelog
Release notes and announcements for the Criteo Retail Media API. Versions are released twice a year, in January and July.
## API Versioning Policy Update
Starting with this release, the Criteo Retail Media API moves to a cadence of **two versions per year**, released in January and July. We are also introducing a new **three-tier release model** — Experimental, Release Candidate, and Stable — replacing the previous two-tier system (Preview and Stable). Find out what this means for your integration in our [Versioning Policy](/criteo-apis/docs/versioning-policy) guide.
## Breaking Changes
* **Retailer Search** — Targeting eligibility is now reported per budget model. `isAvailable` has been removed; use `budgetModelAvailabilities` to see which combinations of budget model, page type, and environment are available for each retailer. For full details, see the [Retailer Search](/retail-media/docs/retailer-search) guide.
* **AI Assistant Page Type** — You can now target AI Assistant placements by including `aiAssistant` as a value in the `pageTypes` field when creating or updating line items. Read more in the [Retailer Search](/retail-media/docs/retailer-search) guide.
* **Real-Time Performance — Metric Renaming** — `billableImpressions` and `billableClicks` have been renamed to `impressions` and `clicks`. Update your integration to use the new names before upgrading to `2026.07`. More information in our dedicated [Real-Time Performance Report](/retail-media/docs/real-time-performance-api) guide.
* **DSP Analytics Reporting Redesign** — The three legacy endpoints (`/reports/campaigns`, `/reports/line-items`, `/reports/accounts`) and the `reportType` field have been replaced by a unified set of purpose-built endpoints where you explicitly declare `metrics` and `dimensions`. Learn more on the following pages: [Analytics Overview](/retail-media/docs/demand-side-analytics-overview), [Performance Report](/retail-media/docs/performance-report), [Missed Opportunities](/retail-media/docs/missed-opportunities-report), [Attributed Transactions](/retail-media/docs/attributed-transactions-report).
## New in Stable
* **Commerce Max — Retailer Budgets Expansion** — Retailer budget management is now fully supported in stable, covering budget visibility, field naming, and eligibility rules across campaigns, line items, and balances. Explore the [Retailer Budgets](/retail-media/docs/retailer-budgets) guide for more information.
* **Real-Time Performance Report** — The synchronous real-time performance report is now available in stable, returning live campaign data immediately without polling. See our dedicated [Real-Time Performance Report](/retail-media/docs/real-time-performance-api) guide.
* **Store Inventory** — You can now programmatically upsert and delete store inventory records, enabling automated inventory management workflows. Full details in the [Store Inventory](/retail-media/docs/store-inventory) guide.
* **Balance Management — PATCH Endpoint** — A new `PATCH` endpoint lets you partially update existing balances without replacing the full record. `retailerPoNumber` replaces `poNumber`, and `endDate` now accepts a Nillable wrapper so you can explicitly set, clear, or leave a date unchanged. Head to our [Balance Management](/retail-media/docs/balance-management) guide to learn more.
## Enhancements
* **SSP Revenue Report** — Three new fields added: `authorizedBuyer` as a new value in the `soldBy` enum, and `budgetModels` and `activationPlatforms` arrays to identify how inventory was monetized. Learn more on the [Revenue Report (SSP)](/retail-media/docs/revenue-report-ssp) page.
## New Features
* **API Authorization — PKCE Support** — Proof Key for Code Exchange (`PKCE`) is now supported as a security enhancement to the OAuth 2.0 Authorization Code flow. When enabled, requests must include a `code_challenge` derived from a `code_verifier`, preventing intercepted authorization codes from being misused. See the [OAuth PKCE setup guide](/retail-media/docs/oauth-app-authorization-code-pkce-setup) for more information.
* **Sponsored Product Line Item Updates** — Four new capabilities added to sponsored product line item endpoints: **Conquesting** for targeting competitor search queries, **Ad Scheduling** for day-of-week and time-of-day delivery controls, **Adaptive CPC** for real-time bid optimization based on predicted conversion probability, and **Flexible Start/End Date Timestamps** supporting `dateTimeOffset` values for timezone-aware scheduling. Full details in the [Sponsored Products Line Items](/retail-media/docs/onsite-sponsored-products-line-items) guide.
* **Retailer Search** — New endpoint to programmatically determine targeting eligibility across available retailers, campaign types, buy types, page types, and environments before creating or updating campaigns. Read more in the [Retailer Search](/retail-media/docs/retailer-search) guide.
* **Account Level Reporting** — New asynchronous reporting endpoint aggregating performance data at the account level across up to five `accountIds` in a single request, with a maximum 31-day date range. More information in the [Account Level Report](/retail-media/docs/account-level-report) guide.
* **Fill Rate Reporting** — Two new reporting endpoints for retailers: a **fill rate report** measuring how effectively ad placements are monetized, and an **unfilled placements report** breaking down the specific reasons inventory went unfilled. Explore the [Fill Rate Report](/retail-media/docs/fill-rate-report) guide.
## New Features
* **API Troubleshooting Guides** — Three new documentation pages introduced: a [Troubleshooting Guide](/retail-media/v2025.10/docs/api-troubleshooting-guide) for diagnosing common API issues, [Escalation Guidelines](/retail-media/v2025.10/docs/escalation-guidelines) defining when and how to escalate to Criteo support, and an [API Error Codes](/retail-media/v2025.10/docs/api-error-codes) reference for interpreting error responses.
* **Retailer Configuration Updates** — New governance logic for Commerce Max demand opt-out: if a retailer opts out of receiving Commerce Max demand, create and edit operations on affected campaigns and line items will return a validation error, while read and reporting operations remain fully accessible.
* **Recommended Keywords** — New endpoint that analyzes your product IDs and returns the top 100 keywords your line items would serve on, letting you preview targeting before adding products to a campaign. See the [Recommended Keywords](/retail-media/v2025.10/docs/recommended-keywords) guide.
* **Recommended Categories** — New endpoint that returns up to 50 recommended product categories for targeting based on your specified products and the retailer's taxonomy. Read more in the [Recommended Categories](/retail-media/v2025.10/docs/recommended-categories) guide.
* **Category Search** — New endpoint to explore and discover available product categories within a retailer's hierarchical taxonomy, helping you understand targeting options before campaign setup. Full details in the [Category Search](/retail-media/v2025.10/docs/category-search) guide.
* **Account Fees** — New endpoints enabling Private Marketplace retailers to search and manage fees across one or more accounts. More information in the [Account Fees](/retail-media/v2025.10/docs/account-fees) guide.
* **Keyword Bid Override on Auto-Targeted Keywords** — Keyword bid overrides can now be applied to automatically targeted keywords (derived from the keyword relevancy model), in addition to manually targeted ones. Head to the [Keywords](/retail-media/v2025.10/docs/keywords) guide for details.
* **Authorization Code Rate Limiting — Auto Scaling** — Rate limits for Authorization Code apps now scale automatically with the number of consented accounts (10 calls/minute per account). Learn more on the [Rate Limits](/retail-media/v2025.10/docs/rate-limits) page.
* **Reporting Updates** — Reporting cache behavior improved (1-hour cache for same-day reports, 24-hour for prior dates). New `productCategory` dimension for advertised product category reporting, updated `capoutMissedTraffic` calculation, and new dimensions on the Attributed Transactions report. More information in our dedicated [Analytics Overview](/retail-media/v2025.10/docs/demand-side-analytics-overview) guide.
## New Features
* **Keyword Review & Approval** — New endpoints enabling retailers to review and approve keywords proposed by advertisers for targeting on retailer inventory, based on relevance, accuracy, and retailer guidelines. See the [Keyword Review](/retail-media/v2025.07/docs/keyword-review) guide.
* **Catalog Export Enhancements** — New `includeFields` filter to scope catalog responses to only relevant fields, and a `modifiedAfter` parameter to fetch only SKUs updated after a given timestamp. Available on both seller and brand catalog export endpoints. Full details in the [Catalog Endpoints](/retail-media/v2025.07/docs/catalog-endpoints) guide.
* **Brand Search** — New endpoint to search for brands by name across the universal catalog and retailer-specific brands, replacing the account-scoped brand lookup workflow. Read more in the [Brands](/retail-media/v2025.07/docs/brands) guide.
* **Partner Billing Report** — New reporting endpoints enabling retailers to bill retailer-contracted advertisers, manage invoicing, and track payments — including fee and media cost verification for campaigns managed through Commerce Max and CYield. More information in the [Partner Billing Report](/retail-media/v2025.07/docs/partner-billing-report) guide.
* **Reporting — Media Type & Attribution Dimensions** — New `mediaType` dimension available as both a dimension and a filter across DSP and SSP reporting endpoints, enabling performance breakdowns by Display or Video. New `clickMatchLevel` and `viewMatchLevel` filters added for SSP attribution reporting. Explore the [Analytics Overview](/retail-media/v2025.07/docs/demand-side-analytics-overview) for more.
## Breaking Changes
* **Keyword Endpoint Cleanup** — Older keyword endpoints supporting only negative keyword targeting have been removed from `2025.04`. Use the unified keyword endpoints that support both negative and positive keyword targeting going forward. See the [Keywords](/retail-media/v2025.04/docs/keywords) guide.
## New Features
* **Private Market Child Accounts** — New endpoint enabling Private Marketplace retailers to retrieve all child accounts associated with their `accountId`. Read more in the [Accounts](/retail-media/v2025.04/docs/accounts-endpoints) guide.
* **Seller Search** — New marketplace seller search endpoint providing a programmatic way to identify all marketplace sellers and associated retailers for a given account, supporting campaign activation workflows. More information in our [Accounts](/retail-media/v2025.04/docs/accounts-endpoints) guide.
* **CPC Minimum Bid** — New endpoint to look up the minimum CPC bid required for a set of sponsored products before adding them to a line item. Full details in the [Sponsored Products Line Items](/retail-media/v2025.04/docs/onsite-sponsored-products-line-items) guide.
* **New Reporting Metrics — Win Rate & Video** — `winRate` metric added for Sponsored Products (bids won / bids participated). New video metrics added for flexible line-item reporting via the DSP API and SSP API. Explore the [Analytics Overview](/retail-media/v2025.04/docs/demand-side-analytics-overview) for the full list.
* **Updated Terms & Conditions** — The API Terms & Conditions have been updated to clarify agreement scope, acceptance requirements, and compliance obligations. Find them on the [Terms & Conditions](/retail-media/v2025.04/docs/criteo-api-terms-and-conditions) page.