Retail Media API Changelog

​

Type-Agnostic Campaign and Line Item Workflow

• Create a campaign

• Create a line item — POST /line-items
• Update a line item — PATCH /line-items/{line-item-id}
• Search line items — demand — POST /line-items/demand-search
• Search line items — supply — POST /line-items/supply-search

• Add products to a line item

​

API Versioning Policy Update

​

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 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 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 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, Performance Report, Missed Opportunities, Attributed Transactions.

• Balance Endpoints — Path Parameters Renamed — The account-id and balance-id path parameters have been renamed to accountId and balanceId across all balance endpoints. Update your request URLs accordingly: GET /accounts/{accountId}/balances, POST /balances/{balanceId}/campaigns/append, POST /balances/{balanceId}/campaigns/delete.

• Balance Endpoints — Pagination Fields Renamed — The pagination metadata fields returned by GET /accounts/{accountId}/balances have been renamed. Replace totalItemsAcrossAllPages, currentPageSize, currentPageIndex, and totalPages with count, offset, and limit.

• Balance Endpoints — Campaign Append/Delete Request Body Restructured — The request body for POST /balances/{balanceId}/campaigns/append and POST /balances/{balanceId}/campaigns/delete has changed from an array (data[]) to a single object (data). Update your payloads to pass campaign IDs under data.attributes.ids.

• Balance Endpoints — spendType Enum Values Recased — The spendType enum values returned by GET /accounts/{accountId}/balances and PATCH /accounts/{accountId}/balances/{balanceId} are now lowercase. Replace Offsite → offsite, OffsiteAwareness → offsiteAwareness, Onsite → onsite. Two new values have also been added: lockout and unknown.

• Balance Endpoints — History changeType Values — changeType values returned by GET /balances/{balanceId}/history are now camelCase (e.g. balanceCreated, endDate, retailerPoNumber). Several new values have also been added: balanceAdded, balanceRemoved, balanceName, criteoPoNumber, retailerId, and unknown. Update any string matching logic in your integration. See the Balance Management guide for the full list of all balance endpoint changes above.

• Creatives & Templates — New creativeFormatType Values — Eight new values have been added to the creativeFormatType enum on creative endpoints (POST/PUT /accounts/{accountId}/creatives) and the creativeFormat enum on template endpoints (GET /retailers/{retailerId}/templates): BrandingDisplayGridSolo, BrandingDisplaySpotlightSolo, BrandingVideoStandout, CommerceDisplayGridDuet, CommerceDisplayGridShelf, CommerceDisplaySpotlight, CommerceVideoGridDuet, CommerceVideoSpotlight. Ensure your integration handles unknown enum values gracefully. See the Creative Builder guide for the full list.

​

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 guide for more information.
• Commerce Max — New Balance Endpoint — A new GET /balances/{balanceId} endpoint lets you fetch a single balance directly by ID without needing the accountId. See the API reference for details.
• 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 guide.
• Store Inventory — You can now programmatically upsert and delete store inventory records, enabling automated inventory management workflows. Full details in the 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 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) 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 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 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 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 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 guide.

​

New Features

• API Troubleshooting Guides — Three new documentation pages introduced: a Troubleshooting Guide for diagnosing common API issues, Escalation Guidelines defining when and how to escalate to Criteo support, and an 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 page.