|
Operation |
Method |
Endpoint |
|---|---|---|
|
Create an entity |
|
|
|
Delete from a list |
|
|
|
Append to a list |
|
|
|
Get all entities |
|
|
|
Get a specific entity |
|
|
|
Update a specific entity |
|
|
|
Operation |
Method |
Endpoint |
|---|---|---|
|
Create a resource request |
|
or
|
|
Retrieve the status of the requested resource |
|
|
|
Retrieve the output of the requested resource |
|
|
|
Attribute |
Type |
Description |
|---|---|---|
|
|
string |
Unique ID for the entity.
|
|
|
string |
Resource data type returned in the response body (for example,
|
|
|
object |
Entity attributes - may be omitted entirely if an entity does not have additional attributes |
|
Attribute |
Type |
Description |
|---|---|---|
|
|
string |
Unique ID for the error response |
|
|
string |
Error category; machine-readable (e.g.
|
|
|
string |
Short machine-readable string for the error (e.g.
|
|
|
string |
URI referencing the endpoint that caused the error |
|
|
string |
Short human-readable string that summarizes the issue |
|
|
string |
Human-readable explanation of the issue |
|
|
object |
Object referencing the field that caused the error |
|
Query Parameters |
Type |
Description |
|---|---|---|
|
|
integer |
Defines the starting point from which records should be returned, i.e., will skip the first
|
|
|
integer |
Specifies the maximum number of entities returned in a single page; defaults to
|
|
Query Parameters |
Type |
Description |
|---|---|---|
|
|
integer |
Returns the specified page of results given a
|
|
|
integer |
Specifies the maximum number of entities returned in a single page; defaults to
|
## Filter by ID All endpoints that retrieve all entities under a specific context supports an optional query parameter `limitToId` that can be used to retrieve the respective element. This param can also be combined multiple times to retrieve multiple elements at the same time. Examples: 1. Retrieve specific Account(s) from endpoint that lists all Accounts 2. Retrieve specific Brand(s) from endpoint that lists all Brands associated with the Account 3. Retrieve specific Retailer(s) from endpoint that lists all Retailers associated with the Account
|
Query Parameters |
Type |
Description |
|---|---|---|
|
|
integer |
Limits results to the entity IDs specified; parameter key is repeated, e.g.
|
*** ## HTTP Response Codes
|
Response |
Description |
|---|---|
|
🔵
|
Request successful |
|
🔵
|
The new entity was successfully created |
|
🔵
|
Request succeeded and no returned content should be expected |
|
🟡
|
This may occur when operating on multiple entities, such as the call resulting in some successes but also some failures |
|
🔴
|
For improper syntax, check your call structure |
|
🔴
|
If unauthenticated, refresh your access token |
|
🔴
|
Insufficient rights to perform this action |
|
🔴
|
Resource not found, check your entity IDs in the call |
|
🔴
|
Request timed out |
|
🔴
|
Request conflicts with something, such as a campaign name that already exists |
|
🔴
|
Too many requests |
|
🔴
|
Something's wrong on Criteo's end... |
|
EMEA |
APAC |
Americas |
|---|---|---|
|
178.250.0.0/21 185.235.84.0/22 91.212.98.0/24 91.199.242.0/24 2a02:2638::/32 |
74.119.116.0/22 199.204.168.0/22 177.73.128.0/21 2620: 100:a000::/44 |
116.213.20.0/22 182.161.72.0/22 2406:2600::/32 |
|
Parameter |
Description |
|---|---|
|
|
Set up your API credentials through our Developer Portal |
|
|
Set up your API credentials through our Developer Portal |
|
|
Must be
|
|
Application |
No access |
Read |
Manage |
|---|---|---|---|
|
Analytics |
Your application will not have access to any of the retail media analytics endpoints. |
Your application will have access to retrieve reporting data using the retail media analytics endpoints. |
|
|
Audiences |
Your application will not have access to any of the retail media audience endpoints. |
Your application will have access to retrieve audiences and make calls to GET endpoints only. |
Your application will have access to all audience endpoints, which includes both
|
|
Campaigns |
Your application will not have access to any of the retail media campaign management endpoints. This includes all campaign and line-item management features, balances, catalogs and creatives. |
Your application can only retrieve campaign man agent details. This includes
|
Your application will have access to all campaign management endpoints, which includes all
|
|
POST |
|
|
POST |
|
|
Parameter |
Description |
|---|---|
|
|
Your public signing key |
|
|
The UNIX timestamp of when your URL was generated, in seconds |
|
|
An arbitrary string to be included in the consent callback (e.g., the User ID of your app user) |
|
|
The URL to redirect the user to after consent delegation |
|
|
The HMAC-SHA512 hashed query string of the previous four parameters, in order |
# Create Your API Application Source: https://developers.criteo.com/criteo-apis/docs/create-your-app ## Introduction Once you have [created your organization](/criteo-apis/docs/create-your-organization), you can access the `My Apps` page to begin creating your application. This page is also where you will manage your Criteo API applications. To start creating your API application, click the `Create a New App` button in the top right corner of the page. This will initiate the application creation process. *** ## Step 1 - Create application ### App details * Provide a name for your application, along with an optional description and app image. Please ensure that **your application has a clear and identifiable name**, as this greatly assists our teams in providing faster and more effective support during troubleshooting.
|
Domain |
Description |
Authorization Types |
|---|---|---|
|
Accounts |
Manages permissions to endpoints responsible for describing accounts' entities, with their properties and relationships, like parent/child accounts |
No access / Read / Manage |
|
Analytics |
Manages permissions to generate reporting data for campaigns & line-items, considering desired list of dimensions & metrics |
No access / Read |
|
Audiences |
Manages permissions to check/manage audiences available to campaigns |
No access / Read / Manage |
|
Balances |
Manages permissions to endpoints responsible for configuring and retrieving balance entities, which define spending limits applied across campaigns linked to an account. |
No access / Read / Manage |
|
Billing |
Manages permissions to generate billing data for campaigns & line items for a retailer partner |
No access / Read |
|
Campaigns |
Manages permissions to endpoints responsible for campaigns management, including line-items, balances and creatives |
No access / Read / Manage |
|
Catalog |
Manages permissions to check/manage products catalogs |
No access / Read / Manage |
# OpenAPI Specifications Source: https://developers.criteo.com/criteo-apis/docs/criteo-api-swagger
These API Terms shall be binding upon and inure to the benefit of the Parties hereto and their successors, representatives, and permitted assigns. *** # EXHIBIT B – IT SECURITY POLICY The following schedule describes the security requirements and associated controls that must be maintained by Partner (including its subcontractors involved in the Data processing, if any) throughout the term of the API Terms. ## Security Governance and Management Partner must maintain an appropriate Security Management System, inclusive of other industry known privacy and security best practices and maintain appropriate security controls. This will include appropriate documentation (security policies, processes, guidelines, standards, configuration standards and associated security controls) to assure adequate protection of Data throughout the Data processing lifecycle, for the term of the API Terms. ## Security Roles and Responsibilities Partner will maintain defined responsibilities for security within their organization with a named contact, and escalation levels, to support Criteo security requirements, including answering general security questions, if required. ## Security and Privacy Awareness Training Partner shall ensure that it is sufficiently trained (at least annually) on necessary security and privacy content and supporting procedures. Such training shall include phishing simulations on a regular frequency. ## Security Assessments Criteo shall have the right, with thirty (30) business days advance notice, to perform security assessments related to Partner and associated use of Data. Criteo shall also have access to information security assessments performed by the Partner and/or any third parties on the use of Data. Additionally, Criteo may request an updated information security compliance report (“Compliance Report”) every twelve (12) months, or earlier if it reasonably considers there have been substantial changes in security requirements, to enable Criteo to assess ongoing compliance with Partner´s information security requirements set herein. If Criteo considers that the Compliance Report is not satisfactory, Partner will communicate, in timely manner, any additional information required by Criteo to demonstrate compliance with this IT Security Policy. ## Security Process Compliance Partner must report detected security incident with one (1) working day delay from the first discovery of the incident on detection to Criteo’s service desk and their assigned management and comply with Criteo security policies, processes and procedures. ## Security Breach Reporting Any detected security breach impacting Data must be immediately reported to Criteo and no more than one (1) working day after detection, with a detailed formal security incident report provided no later than two (2) working days after detection. All formal security incident reports must include root cause analysis and detailed forensic and log information, including total quantity of personal data records impacted, if applicable. ## Physical and Environmental Security Controls Partner will maintain appropriate physical and environmental security controls to protect against data security risks and to protect the confidentiality, the integrity and the availability of Data if processed, transmitted or stored within their premises. All such controls will be aligned to applicable industry, operational and security best practices protecting against physical and environmental security risk, including physical access controls, physical security monitoring and environmental protections against power disruptions, fire hazards, and related operational risks. ## Access Control Partner shall ensure that it maintains the following best practice controls for the accounts in charge of maintaining the activities within the API Terms with all granting of accounts based on defined roles and permissions: a) All accounts and permissions granted for the express use in relation to Data processing; any use sharing of granted accounts is a security breach unless expressly approved by Criteo.\ b) All accounts must apply appropriate password complexity, length and special characters. Multi-factor authentication (“MFA”) should be applied.\ c) Any compromise of a granted accounts or permissions must be reported as a security incident to Criteo’s service desk on detection.\ d) Use of service accounts must comply with Criteo’s application standards.\ e) All use of credentials and keys related to Criteo applications and Data must comply with applicable company configurations and standards. ## Device Security The following device security controls must be maintained throughout the duration of the API Terms where Partner utilizes its own devices: a) Device must be centrally managed by appropriate management systems to support active software and hardware security management.\ b) Antivirus or Endpoint Detection and Response (“EDR”) (in this case, the EDR should include an antivirus) must be maintained on all devices with 24x7x365 security monitoring and security response with appropriate controls to actively update and protect against most recent malware threats and risks.\ c) Device operating systems must be hardened with appropriate security configuration baselines maintained and regularly deployment of security updates deployed aligned to known operating system patching cycles.\ d) Device data storage and backups must be maintained, applied and tested on an appropriate frequency to ensure availability of data in response to data loss, ransomware.\ e) Data stored on devices must be appropriately encrypted. ## Network Security The following network security controls must be maintained if Partner accesses Criteo applications: a) An appropriate tiered and segmented network architecture must be maintained and monitored for production network.\ b) All traffic across internal or external Partner networks must be encrypted through secure protocols.\ c) Networks (WAN, LAN and WIFI) must be appropriate designed and maintained ensuring appropriate authentication and encryption applied. All networking components, appliances, devices and software must be current and patched appropriately.\ d) In the production network, network and network security must be monitored with appropriate levels of security event and logging present to support effective security incident detection and response.\ Data Backup and Storage: Partner will maintain appropriate data storage and backup routines and activities to ensure data availability, integrity and data recovery on an appropriate frequency to minimize data loss. ## Application Security and Secure Development Lifecycle (SDL) Security The following security controls are applicable if Partner supports processing, transmission or storage of Criteo Data within its service platforms or applications:\ a) Appropriate SDL controls must be maintained for software development aligned to industry recognized standards.\ b) Software must be deployed through controlled SDL with appropriate security and quality assurance tests applied before deployment into production.\ c) Software repositories must be secure through authenticated access controls applied to user and service accounts with code scans to ensure security monitoring and automated updates.\ d) Penetration Testing must be applied on a minimum of an annual frequency with summary findings and identified corrective actions provided to Criteo if requested. ## Vulnerability and Patch Management Partner will maintain appropriate controls for regular vulnerability management scans applied to any applications processing, transmitting or storing Data. Such scans should be a least monthly to identify critical vulnerabilities and support effective mitigation. Patch Management controls must be in place and automated to effectively support security and version updates to proactively protect Data. ## Business Continuity Management (BCM) System Partner, if processing, transmitting and/or storing Data, must maintain an appropriate Business Continuity Management System with supporting continuity and disaster recovery process and controls. Such activities must be appropriately maintained and tested with clear define roles, responsibilities and escalation protocols. # Manage Your Account, Organization and Apps Source: https://developers.criteo.com/criteo-apis/docs/developer-accounts-organizations-apps This section provides guidance on managing your Developer Account, Organization, and Apps once created. ## Manage your Developer Account ### Update account information If you need to update your account information, you can do so by logging into the Criteo Partner Portal. This guide will walk you through the steps to edit your account details. 1. Click the user icon in the top right corner of the page to access your account information.
|
Parameters |
Description |
|---|---|
|
|
Your public key, accessible in the app credentials section. You can manage up to 5 pairs of credentials, even after the app has been activated. |
|
|
Your secret key, accessible only once when creating a pair of
|
|
|
The URL to redirect the user to after consent. Requires HTTPS. You can add up to 30 redirect URIs, manageable after app activation. |
|
Parameters |
Required |
Description |
|---|---|---|
|
|
Yes |
Indicates that an authorization code is expected as outcome. |
|
|
Yes |
Your public key from the app credentials section. |
|
|
Yes |
The URL to redirect the user after consent. Must match the configured URI. |
|
|
No |
Optional string to prevent Cross-Site Request Forgery attacks. |
|
Parameter |
Description |
|---|---|
|
|
A single-use authorization code valid for 60 seconds. |
|
|
The originally provided state parameter, returned as-is. |
|
Parameter |
Description |
|---|---|
|
|
Indicates that you are providing an authorization code |
|
|
Authorization code returned during redirection |
|
|
Must match the
|
|
|
Your public key from the app credentials |
|
|
Your secret key, accessible when creating credentials |
|
Parameter |
Description |
|---|---|
|
|
A short-lived (valid for 900 seconds) access token. |
|
|
A long-lived refresh token (that expires after 6 months) that can be used to renew the access token (see next section). |
|
|
Type of token. |
|
|
Lifetime of the token in seconds. |
|
Parameter |
Description |
|---|---|
|
|
Indicates that you are providing a refresh token. |
|
|
Refresh token shared when requesting an access token. |
|
|
Your public key accessible in app credentials section. |
|
|
Your secret key, accessible only once when creating a pair of
|
|
Parameter |
Required |
Description |
|---|---|---|
|
|
Yes |
Indicates that an authorization code is expected as outcome. |
|
|
Yes |
Your public key from the app credentials section. |
|
|
Yes |
The URL to redirect the user after consent. Must match the configured URI. |
|
|
No |
Optional string to prevent Cross-Site Request Forgery attacks. |
|
|
Yes when PKCE is enabled |
A challenge derived from the
|
|
|
No |
A method that was used to derive
The methods available:
|
|
Parameter |
Description |
|---|---|
|
|
Indicates that you are providing an authorization code. |
|
|
Authorization code returned during redirection. |
|
|
Must match the
|
|
|
Your public key from the app credentials. |
|
|
Your secret key, accessible when creating credentials. |
|
|
A high-entropy random string created by the client (usually 43–128 characters). |
|
Parameter |
Description |
|---|---|
|
|
Indicates that you are providing a refresh token. |
|
|
Refresh token shared when requesting an access token. |
|
|
Your public key accessible in app credentials section. |
|
|
Your secret key, accessible only once when creating a pair of
|
# OAuth App - Client Credentials Setup Source: https://developers.criteo.com/criteo-apis/docs/oauth-app-client-credentials This guide provides step-by-step instructions on setting up an API application using the client credentials workflow # Setting up an client credentials application ## Client Credential Log in to the Criteo Partners Portal and create a new app by clicking the ➕ button in the `My apps` section.
# OAuth App Implementation Source: https://developers.criteo.com/criteo-apis/docs/oauth-app-implementation # Introduction The Criteo API enables the creation of custom apps to help advertisers grow their businesses. Whether you're a brand, agency, retailer, or third-party partner, the Criteo API offers various authentication methods to suit your application's needs. To get started, your users must delegate permissions for one or more Criteo advertisers they oversee for your application to function. Criteo supports OAuth client credentials and authorization code grant types. This guide explains the benefits of each grant type, helping you choose the best option for your application.
# Rate Limits Source: https://developers.criteo.com/criteo-apis/docs/rate-limits This page describes the Criteo API rate limit policy, and provides some best practices to help manage rate limits ## Introduction The Criteo API enforces a **rate limit**, which consists of a limitation in the number of calls you're able to perform on any of its endpoints. This limitation is enforced to provide all our API clients with stability towards our API infrastructure. *** ## Rate Limits Criteo provides different rate limits depending on the OAuth method used by your application. | OAuth Method | Rate limit | Applies at | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------- | | [Client Credentials](/criteo-apis/docs/oauth-app-client-credentials) | **250 calls/min** (default endpoints)
**40 calls/min** (reporting endpoints) | Application level | | [Authorization Code](/criteo-apis/docs/oauth-app-authorization-code) | **10 calls/min** | Account level |
|
Header |
Description |
Example response with a limit set at 20 calls/minute |
|---|---|---|
|
|
the currently authorized limit for this caller |
20 |
|
|
the remaining calls for this caller (so, limit - current rate) |
0 |
|
|
the timestamp at which a new call could be performed |
1628249355 |
## What's next * [Accounts Endpoints](/retail-media/docs/accounts-endpoints) * [Account Creation and Management (Private Market)](/retail-media/docs/account-creation-and-management-private-market) * [Account Fees (Private Market)](/retail-media/docs/account-fees) * [Brands](/retail-media/docs/brands) * [Sellers](/retail-media/docs/sellers) * [Retailers](/retail-media/v2025.07/docs/retailers) # Account Creation and Management (Private Market) Source: https://developers.criteo.com/retail-media/docs/account-creation-and-management-private-market Account creation endpoints enable private market retailers to create both demand brand and marketplace seller accounts within the private market. The following endpoints will also provide access to manage the brand and seller mappings for each account types.
|
Verb |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Get all Accounts |
|
GET |
|
Get all PM Demand Child (brand or seller) Accounts under the parent Supply Account (Retailer) |
|
POST |
|
Create a PM Demand-Brand Account under the Parent Supply Account |
|
POST |
|
Create a PM Demand-Seller Account under the Parent Supply Account |
|
POST |
|
Map brands to a demand brand account |
|
POST |
|
Remove brand from a demand brand account |
|
PUT |
|
Map or remove sellers from demand seller account. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Account ID, from a demand or supply account, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Account name, arbitrary and defined at account creation Accepted values: up to 510-chars string Writeable? Y / Nullable? N |
|
|
enum |
Account type, with
Accepted values:
Writeable? N / Nullable? N |
|
|
enum |
Account sub-type, specific for demand accounts
Accepted values:
Writeable? N / Nullable? Y |
|
|
list
|
List of Brand IDs associated with a demand brand account. Required in the demand brand account creation. Accepted values: list of string of int64 Writeable? Y / Nullable? N |
|
|
string |
Seller ID from Retailer's Catalog , associated with a demand seller account. Required in the demand seller account creation. Accepted values: string of int64 Writeable? Y / Nullable? N |
|
|
string |
Retailer ID, associated with the demand seller account, generated internally by Criteo. Required in the demand seller account creation. Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company associated with the advertisement. Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
|
string |
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company (on behalf of
Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
|
list
|
Countries associated with the account
Accepted values: 2-chars country code (in
ISO-3166
alpha-2 code; e.g.
Writeable? N / Nullable? N |
|
|
string |
Default currency for bulling, budgeting, bid settings & campaign performance metrics
Accepted values: 3-chars currency code (in
ISO-4217
; e.g.
Writeable? N / Nullable? N |
|
|
string |
Label used to associate multiple accounts Accepted values: up to 510-chars string
Default: same as
Writeable? Y / Nullable? N |
|
|
string |
Account time zone
Accepted values: time zone identifiers from
IANA (TZ database)
(e.g.
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🔵
|
Call completed successfully |
|
🔵
|
Account created successfully |
|
🔴
|
Validation Error - one or more required fields was not found. Confirm that all required fields are present in the API call |
## What's next * [Account Fees (Private Market)](/retail-media/docs/account-fees) * [Brands](/retail-media/docs/brands) * [Sellers](/retail-media/docs/sellers) * [Retailers](/retail-media/v2025.07/docs/retailers) # Account Fees (Private Market) Source: https://developers.criteo.com/retail-media/docs/account-fees ## Introduction The **Account Fees API** allows Private Market retailers to manage fee settings for their accounts through the external API. This includes retrieving fees for one or more accounts and updating those fees where permitted. *** ## Endpoints
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
This endpoint allows users to retrieve fee settings for one or more accounts they have access to. |
|
POST |
|
This endpoint allows Private Market retailers to update fees for child seller or demand accounts. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Account ID Up to 25 account IDs can be queried at once.
Accepted values: string of
Writeable: Y/ Nullable: N |
|
Query Parameters |
Data Type |
Description |
|---|---|---|
|
|
|
Pagination parameter, see API Response |
|
|
|
Pagination parameter, see API Response |
|
|
|
Comma-separated list of optional attributes to include in the response. Used to optimize response time and payload length. |
|
Attribute |
Data Type |
Description |
Writable |
Nullable |
|---|---|---|---|---|
|
|
|
Account ID
Accepted values: string of
|
Y |
N |
|
|
|
Defines the set of fees you can set on the Account. Possible values:
|
N |
N |
|
|
|
Value to apply as the
Accepted range: 0.00 to 1.00 Max precision: 2 decimal places |
Y |
N |
|
|
|
The managed service fee that is applied to the account. Options:
|
N |
N |
|
|
|
Indicates if
|
Y |
N |
|
|
|
Indicates if
|
Y |
N |
|
Response |
Title |
|---|---|
|
🟢
|
Success |
|
🔴
|
Bad Request: Model Validation Error. Check that the acceptable values for the attributes are correct. |
|
🔴
|
API user does not have the authorization to make requests to the account ID. For an authorization request, follow the authorization request steps . |
# Accounts Endpoints Source: https://developers.criteo.com/retail-media/docs/accounts-endpoints ## Introduction An account represents a brand, agency, marketplace seller, or retailer. It serves as a business and billing entity that contains campaigns.
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Get all Accounts |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Account ID, from a demand or supply account (generated internally by Criteo) Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Account name, arbitrary and defined at account creation Accepted values: up to 510-chars string Writeable? Y / Nullable? N |
|
|
enum |
Account type, with
Accepted values:
Writeable? N / Nullable? N |
|
|
enum |
Account sub-specific for demand accounts
Accepted values:
Writeable? N / Nullable? Y |
|
|
list\\ |
Countries associated with the account
Accepted values: 2-chars country code (in ISO-3166 alpha-2 code; e.g.
Writeable? N / Nullable? N |
|
|
string |
Default currency for bulling, budgeting, bid settings & campaign performance metrics
Accepted values: 3-chars currency code (in ISO-4217; e.g.
Writeable? N / Nullable? N |
|
|
string |
Label used to associate multiple accounts Accepted values: up to 510-chars string
Default: same as
Writeable? Y / Nullable? N |
|
|
string |
Account time zone
Accepted values: time zone identifiers from IANA (TZ database) (e.g.
Writeable? N / Nullable? N |
|
|
string |
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company associated with the advertisement. Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
|
string |
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company (on behalf of
Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
Response |
Description |
|---|---|
|
🟢
|
Call executed with success |
## What's next * [Account Creation and Management (Private Market)](/retail-media/docs/account-creation-and-management-private-market) * [Account Fees (Private Market)](/retail-media/docs/account-fees) * [Brands](/retail-media/docs/brands) * [Sellers](/retail-media/docs/sellers) * [Retailers](/retail-media/v2025.07/docs/retailers) # Algebra Nodes Source: https://developers.criteo.com/retail-media/docs/algebra-nodes ## Introduction Algebra nodes are the way to mix different Audience Segments. For example, when you want to include users that belong to more than one segment at the time or if you want to exclude users of a specific segment. Each Audience has one Algebra Node, and within it, you can mix your segments to build the audiences you want. Also, algebra nodes can be mixed together in a flexible way. There are four types of nodes available, and they follow a JSON notation: * **Audience Segment nodes**: Segments with no operator. * **AND nodes**:To include the users that belong simultaneously to all the segments within it (like an intersection). * **OR nodes**: To Include users that belong to any of the segments within it. * **NOT nodes**: To not include the users that belong to the segments within it. *** ## Audience Segment node ```json Examples Audience Segment ID node theme={null} // Target users that belong to a single Audience Segment { "audienceSegmentId": "920472839472539402" } ``` ## AND node Use it to include the users that belong simultaneously to all the segments within it (like an intersection). ```json Examples AND node expandable theme={null} // Target users that belong to three Audience Segments "and": [ { "audienceSegmentId": "920472839472539402" }, { "audienceSegmentId": "233219483716673812" }, { "audienceSegmentId": "333772819393817832" } ] // Target users that belong to two groups of Audience Segments "and": [ { "or": [ { "audienceSegmentId": "920472839472539402" }, { "audienceSegmentId": "233219483716673812" } ] }, { "or": [ { "audienceSegmentId": "826202615157899221" }, { "audienceSegmentId": "100859273425167728" } ] } ] // Target users that belong to the first group of Audience Segments (42914 or 19234) but not on the last one (144219) "and": [ { "or": [ { "audienceSegmentId": "281929273626192303" }, { "audienceSegmentId": "625702934721171442" } ] }, { "not": { "audienceSegmentId": "194652937100327617" } } ] ``` ## OR node ```json Example OR node theme={null} // Target users that belong to any of these Audience Segments { "or": [ { "audienceSegmentId": "194652937100327617" }, { "audienceSegmentId": "100859273425167728" }, { "audienceSegmentId": "826202615157899221" } ] } ``` ## NOT node Use it to not include the users that belong to the segments within it. ```json Example NOT node theme={null} // Target users that do not belong to the single Audience Segment { "not": { "audienceSegmentId": "194652937100327617" } } // Target users that do not belong to any of these Audience Segments { "not": { "or": [ { "audienceSegmentId": "920472839472539402" }, { "audienceSegmentId": "826202615157899221" } ] } } // Target users that do not belong to these Audience Segments { "not": { "and": [ { "audienceSegmentId": "920472839472539402" }, { "audienceSegmentId": "826202615157899221" } ] } } ``` ***
# Demand Side Analytics (DSP) Source: https://developers.criteo.com/retail-media/docs/analytics The Criteo Retail Media Analytics API allows you to scale operations programmatically through our API and integrate Retail Media Platform (RMP) capabilities into your preferred UI or workflow tools. With the Criteo Retail Media API You will be able to download campaign and line item performance reports, including: * Product-level performance and attributed transaction logs, * Report attribution windows and time zones are fully customizable. *** ## Quick Start 1. Request a report 2. Poll for report status 3. Upon success, download the report output ***
## What's next * [Overview](/retail-media/docs/demand-side-analytics-overview) * [Migrating from the legacy reporting API](/retail-media/docs/dsp-analytics-migration-guide) * [Performance Report](/retail-media/docs/performance-report) * [Real-Time Performance Report](/retail-media/docs/real-time-performance-api) * [Missed Opportunities Report](/retail-media/docs/missed-opportunities-report) * [Attributed Transactions Report](/retail-media/docs/attributed-transactions-report) * [Reporting Diagnostic Guide](/retail-media/docs/reporting-overview-diagnostic-guide) # Attributed Transactions Report Source: https://developers.criteo.com/retail-media/docs/attributed-transactions-report POST /reports/attributed-transactions — transaction-level log of every purchase event attributed to Retail Media DSP campaigns. This endpoint enables Retail Media DSP partners to retrieve a transaction-level log of every purchase event attributed to their campaigns. Each row represents a single attributed transaction and captures the product advertised, the product purchased, the attribution rule applied, and the time elapsed between ad delivery and purchase.
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Search for audiences by audience IDs, retailer IDs and/or segment IDs. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Audience ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Audience name Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Description of the Audience Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Account ID associated with the Audience, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Retailer ID, associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
object |
Algebra node with the definition of how the different audience segments are combined together to create the audience, using logical operators
Accepted values: see Algebra Nodes Writeable? N / Nullable? N |
|
|
timestamp |
Timestamp of Audience creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
string |
User ID who created the Audience (
Accepted values: string Writeable? N / Nullable? Y |
|
|
timestamp |
Timestamp of last Audience update, in UTC
Accepted values:
Writeable? N / Nullable? N |
## What's next * [Audience Segment Endpoints](/retail-media/docs/audience-segment-endpoints) # Audience Segment Endpoints Source: https://developers.criteo.com/retail-media/docs/audience-segment-endpoints ## **Introduction** **Audience Segments** represent groups of users, defined through `Contact Lists` provided externally. Multiple **Audience Segments** can be combined using logical [Algebra Nodes](/retail-media/docs/algebra-nodes) to define the desired target audience for your campaigns.
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Create a new Audience Segment |
|
PATCH |
|
Update an Audience Segment |
|
POST |
|
Delete an Audience Segment |
|
POST |
|
Search for Audience Segments by segment IDs, retailer IDs and/or segment types |
|
GET |
|
Retrieve contact list statistics |
|
POST |
|
Add/remove identifiers in contact list Audience Segment |
|
POST |
|
Clear all identifiers in contact list Audience Segment |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Audience Segment ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Audience Segment name Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Description of the Audience Segment Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Account ID associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Retailer ID, associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
enum |
Type of segment Accepted values:
Writeable? Y / Nullable? N |
|
|
object |
Setting to target users with contact list. Note, either one of
See below for more details |
|
|
timestamp |
Timestamp of Audience Segment creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
string |
User ID who created the Audience Segment (
Accepted values: string Writeable? N / Nullable? Y |
|
|
timestamp |
Timestamp of last Audience Segment update, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
list
|
Channels associated to the audience
Accepted values:
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
boolean |
Indicates if the contact list can be edited
Accepted values:
Writeable? N / Nullable? N |
|
|
enum |
User identifier type from Contact list
Accepted values:
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
enum |
Operation required for the sub-set of users provided in the request
Accepted values:
Writeable? N / Nullable? N |
# Audiences Source: https://developers.criteo.com/retail-media/docs/audiences An audience represents all users who interacted with specific brands or categories over a defined period, and can be specifically targeted for your campaigns. [Audience Endpoints](/retail-media/docs/audience-endpoints) [Audience Segment Endpoints](/retail-media/docs/audience-segment-endpoints)
## What's next * [Audience Endpoints](/retail-media/docs/audience-endpoints) * [Audience Segment Endpoints](/retail-media/docs/audience-segment-endpoints) * [Algebra Nodes](/retail-media/docs/algebra-nodes) # Balances Source: https://developers.criteo.com/retail-media/docs/balances
## What's next * [Balances Endpoints](/retail-media/docs/balances-endpoints) # Balances Endpoints Source: https://developers.criteo.com/retail-media/docs/balances-endpoints View and manage all available balances across campaigns
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Retrieve all balances associated with a specific account. |
|
GET |
|
Retrieve a specific balance |
|
POST |
|
Create a new balance for a specified account. |
|
PATCH |
|
Modify balance's metadata (name, start/end date - for deposited funds, see below) |
|
POST |
|
Add/remove funds deposited in a specific balance. |
|
GET |
|
Retrieve all campaigns linked to a specific balance. |
|
POST |
|
Add campaigns to a specific balance. |
|
POST |
|
Remove campaigns from a specific balance. |
|
GET |
|
Retrieve all changes made historically to a balance |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Balance ID Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
|
Balance name Accepted values: up to 255-char strings Writeable? Y / Nullable? N |
|
|
|
Amount of funds deposited; uncapped if
Accepted values:
Writeable? Y / Nullable? Y |
|
|
|
Amount of funds already spent
Accepted values: 0 ≤
Writeable? N / Nullable? N |
|
|
|
Amount of funds already spent
Accepted values: 0 ≤
Writeable? N / Nullable? Y |
|
|
|
Balance start date; if time zone is not set, will consider Account 's time zone as default
Accepted values:
Writeable? Y / Nullable? N |
|
|
|
Balance end date; if time zone is not set, will consider Account 's time zone as default
Accepted values:
Default: if
Writeable? Y / Nullable? Y |
|
|
|
Balance current status
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Timestamp of balance creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Timestamp of last balance update, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
|
An optional memo note that can be set in the balance Accepted values: up to 250-char strings Writeable? Y / Nullable? Y |
|
|
|
The balance type is computed based on the deposited amount:
Accepted values:
Writeable? N / Nullable? N
|
|
|
|
The type of balance that will be used based on the campaign type
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Billing type of the balance
Accepted values:
⚠️ Note :
Writeable? N / Nullable? N |
|
|
|
Retailer this balance is scoped to. Present only on retailer budgets. Nullable? Y (null for balances without retailer budgets) |
|
|
|
Retailer purchase order number.
Replaces
the removed
Nullable? Y |
|
|
|
Criteo purchase order number.
Replaces
the removed
Nullable? Y |
|
|
|
Purchase order number.
Removed since 2026.01
and replaced by
Accepted values: up to 32-char strings Writeable? Y / Nullable? Y |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Timestamp of balance update
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Username who modified the insertion order Accepted values: strings in format "j.doe" Writeable? N / Nullable? N |
|
|
|
Definition of the type of change in a balance
Accepted values:
|
|
|
|
Structure with the change details (from Balance History endpoint) Parameters:
|
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Difference amount of fund to be added/removed from balance; it cannot reduce the current amount of funds deposited to less than zero
Accepted values:
Writeable? N / Nullable? N |
|
|
|
New retailer purchase order number Accepted values: up to 32-char strings Writeable? Y / Nullable? Y |
|
|
|
A memo note that should be set in the balance together with this modification Accepted values: up to 250-char strings Writeable? Y / Nullable? Y |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Campaign ID, respective to the campaign(s) currently appended to the balance Accepted values: string of int64 Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Campaign IDs to append or remove from the balance Accepted values: array of int64 strings Writeable? Y / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Campaign IDs to append or remove from the balance Accepted values: array of int64 strings Writeable? Y / Nullable? N |
|
Response |
Title |
Detail |
Troubleshooting |
|---|---|---|---|
|
🟢
|
Call executed with success |
||
|
🟢
|
Balance request created with success |
||
|
🔴
|
Error deserializing request |
Field xyz is not valid |
Review the value of field xyz provided in the request |
|
🔴
|
Change data capture type xxx is not supported |
Change data capture type xxx is not supported |
The value of
|
|
🔴
|
Invalid name |
Balance name should be unique. There exists balance with the specified name. Balance creation/update has been canceled |
Check value of
|
|
🔴
|
Invalid deltaamount |
Can not decrease funds to less than zero |
Review value of
|
|
🔴
|
Invalid operation |
Can only change the field xxx of a balance not billed by retailer. |
Cannot edit balances not created through the API; only balances with billing type
|
|
🔴
|
Invalid operation |
Can not add funds to a balance not billed by retailer. |
Cannot edit balances not created through the API; only balances with billing type
|
|
🔴
|
Authorization error |
Resource access forbidden: does not have permissions |
One of the permission levels was not respected. Make sure that the respective API app has access to:
|
# Bid Multipliers Source: https://developers.criteo.com/retail-media/docs/bid-multipliers ## Introduction The Criteo engine maximizes advertising performance while optimizing the shopper experience. It can automatically and intelligently control how much a line item delivers on each page type. In addition, bid multipliers provide campaign managers more control over managing bids at the line item level while also optimizing campaign performance goals at a page-type level. Bid multipliers are available at the Onsite Sponsored Products line items level. In addition, campaign managers can modify bids only on enabled page types. Bids can be **increased up to 500%** or **decreased up to 50%** on each page targeted at the line item level. **For example:** If a line item bid is \$1, with a bid multiplier, you can increase the Search page bid by 20% and decrease the homepage bid by 10%. The Criteo engine will optimize more delivery and performance on the search page while also allowing the control of which page types budget is mostly allocated towards. *** ## Endpoints
|
Verb |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Returns all bid multipliers per page types of the specified line item. |
|
PUT |
|
Updates bid multipliers with new values or reset to default one. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Line item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
decimal |
Bid multiplier to the
Note: bids can be increased up to 500% (6.0) or decreased up to 50% (0.50)
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
Response |
Description |
|---|---|
|
🔵
|
Call executed with success |
|
🔴
|
BidMultiplierOutOfRange A bid multiplier provided is out of range of the expected range and could not be accepted IllegalValueProvided An invalid page type or poorly formatted bid multiplier was provided |
|
🔴
|
Unauthorized User doesnt have permission to edit a specified line item |
|
🔴
|
LineItemDoesntExist Attempted to fetch or manipulate a line item that does not exist |
## What's next * [Partner Billing Report](/retail-media/docs/partner-billing-report) * [PBR Metrics](/retail-media/docs/pbr-metrics) # Brands Source: https://developers.criteo.com/retail-media/docs/brands ## Introduction A brand is a collection of products marketed and sold under a unified name. The brands associated with an account define the products that the account can promote on retailer sites. An account can have access to one or more brands, and this access is typically managed by Criteo. Brand attributes are standardized across retailers to ensure consistency. *** ## Endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Get Brands |
|
POST |
|
Search for Brands by name in Retailer(s) Catalogs |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Brand ID, generated internally by Criteo and originated from brand name provided in retailer's Catalog Accepted values: int64 Writeable? N / Nullable? N |
|
|
string |
Brand name, keyword to use as filter in the search (case-insensitive) or returned as final brand name available Accepted values: string Writeable? N / Nullable? N |
|
|
list |
List of Retailer IDs, to use as filter in the search or returned as containing the specific brand Accepted values: list of strings of int32 Writeable? N / Nullable? N |
|
|
enum |
Type of brands, to consider in the search or returned as attribute of the specific brand
Accepted values:
Default:
Writeable? N / Nullable? N |
|
Response |
Error |
Message |
Description |
|---|---|---|---|
|
🟢
|
Call completed successfully |
||
|
🔴
|
Validation Error |
|
One of the parameters provided in the request does not match the format accepted. Check the error details and the parameters informed in the call |
|
🔴
|
Authorization Error |
|
API user does not have the authorization to make requests to the account ID. For an authorization request, follow the authorization request steps |
## What's next * [Sellers](/retail-media/docs/sellers) * [Retailers](/retail-media/v2025.07/docs/retailers) # Budget Overrides Source: https://developers.criteo.com/retail-media/docs/budget-overrides This feature provides more flexibility that allow advertisers to override a line-item budget for specific days or months. ## Introduction You can set a monthly/daily budget override to temporarily spend more or less than the current monthly/daily budget for the months you specify. The override will take effect at midnight in your time zone on the first day of the month or first day of the range you select. *** ## Endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
|
|
Retrieves all existing budget overrides at the campaign level. |
|
|
|
Replaces all existing campaign budget override settings. Use this endpoint can be used to add/remove or update existing budget overrides. |
|
|
|
Retrieves all existing budget overrides at the line-item level. |
|
|
|
Replaces all existing line-item budget override settings. Use this endpoint to add/remove or update existing budget overrides. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
list
|
Line item budget override monthly part, chronological order restricted Parameters:
|
|
|
list
|
Line item budget override daily part, chronological order restricted Parameters:
|
|
|
string |
Start month of monthly budget override.
Accepted values: strings of date
Writeable? Y / Nullable? Y |
|
|
date |
Start date of daily budget override
Accepted values:
Writeable? Y / Nullable? Y |
|
|
string |
The number of
months
(for monthly Budget Override) or
days
(daily Budget Override) that the override is active, from
Accepted values:
Writeable? Y / Nullable? N |
|
|
decimal |
Monthly budget override maximum monthly spend amount
Accepted values:
Writeable? Y / Nullable? N |
|
|
decimal |
Daily budget override maximum daily spend amount
Accepted values:
Writeable? Y / Nullable? N |
|
|
enum |
Monthly or daily budget override computed status
Accepted values:
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🔵
|
Call executed with success |
|
🔵
|
Budget override was created with success |
|
🔴
|
|
## What's next * [Minimum Bid](/retail-media/docs/minimum-bid) # Campaigns Source: https://developers.criteo.com/retail-media/docs/campaign This page is an overview of how to get started with Campaigns ## The Campaign Level Campaigns are created at the account level and are composed of one or several Line Items.
## What's next * [Campaigns Endpoints](/retail-media/docs/campaigns-endpoints) # Campaigns Endpoints Source: https://developers.criteo.com/retail-media/docs/campaigns-endpoints View and manage all your campaigns ## Endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Create a new campaign for the specified account. |
|
GET |
|
Retrieve all campaigns associated with the specified account. |
|
GET |
|
Retrieve details of a specific campaign by its ID. |
|
PUT |
|
Update details of a specific campaign by its ID. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Campaign ID, generated internally by Criteo Accepted values: int64 Writeable? N / Nullable? N |
|
|
|
Account ID associated with the campaign, generated internally by Criteo Accepted values: int64 Writeable? N / Nullable? N |
|
|
|
Campaign name; must be unique within an Account Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
|
Campaign type If the attribute is passed in the call, a value must be specified
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
|
Campaign lifetime spend cap; uncapped if omitted or set to
Note that preferred campaign types cannot have budgets as these campaign types must be uncapped Accepted values: equals/greater than zero
Default:
Writeable? Y / Nullable? Y |
|
|
|
Amount the campaign has already spent Accepted values: equals/greater than zero
Default:
Writeable? N / Nullable? N |
|
|
|
Amount the campaign has remaining until cap is hit;
Accepted values: between zero and
Default:
Writeable? N / Nullable? Y |
|
|
list
|
List of brand IDs from promoted products in the campaign, originated from the retailer's Catalog * see also Brands Accepted values: list of strings Default: empty list Writeable? N / Nullable? N |
|
|
|
Post-click attribution window
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
|
Post-view attribution window
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
|
Post-click attribution scope
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
|
Post-view attribution scope
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
list
|
List of Balances the campaign is able to draw from; at least one balance is required for a campaign to start
Accepted values: list of
Default: empty list Writeable? Y / Nullable? N |
|
|
|
Campaign status, derived from the status of
Line Items
it holds;
Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
|
The maximum monthly spend allowed for the campaign in the currency of the account. The spend is constrained by remaining account balance and total budget of the campaign. Monthly budget spend reset monthly at the start of the month based on the account timezone
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
|
The maximum daily spend allowed for the campaign in the currency of the account, as long as not set to
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
|
Auto daily pacing flag for the campaign budget. The daily pacing value is automatically calculated with respect to the days left in the month for the account. The campaign's remaining account balance, total budget, and monthly pacing value are constrained by account's timezone and the campaign status. If auto daily pacing is enabled,
Note the value may be affected by budget override. Daily budget spend is reset daily at the start of the day based on the account timezone. To activate, either campaign's
Accepted values:
Writeable? Y / Nullable? N |
|
|
|
Campaign start date. The campaign starts inactive if invalid start date is not today or end date is in previous day.
Accepted values:
Default: creation timestamp Writeable? Y / Nullable? Y
⚠️
Note
: if time/timezone designators are not provided, the default value to be considered will be
|
|
|
|
Campaign end date. The campaign starts inactive if invalid start date is not today or end date is in previous day
Accepted values:
Default:
Writeable? Y / Nullable? Y
⚠️
Note
: if time/timezone designators are not provided, the default value to be considered will be
|
|
|
|
Timestamp of campaign creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Timestamp of last campaign update, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
|
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company associated with the advertisement. Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
|
|
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company (on behalf of
Accepted values: up to 255-chars string Writeable? Y / Nullable? Y |
|
|
|
The retailer this campaign is associated with. Required when using a retailer budget balance. Writeable? Y (at create) / Nullable? Y (for non-retailer-budget campaigns) |
# Catalog Endpoints Source: https://developers.criteo.com/retail-media/docs/catalog-endpoints Generate and download a copy of retailer's inventory # Endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Create a catalog request to generate a new catalog for Brand account |
|
POST |
|
Create a catalog request to generate a new catalog for Seller account |
|
POST |
|
Create a request to export existing catalogs from a Brand account |
|
POST |
|
Create a request to export existing catalogs from a Seller account |
|
GET |
|
Retrieve the status of a specific catalog request. |
|
GET |
|
Download the output of a specific catalog once it's ready. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
enum |
Format of the catalog data returned.
Accepted values:
Default:
Writeable? N / Nullable? Y |
|
|
list
|
Brand ID(s) used to filter down catalog results based on specified brands.
Accepted values: list of
Writeable? N / Nullable? N |
|
|
list
|
Retailer ID(s) used to filter catalog results based on specified retailers. If not specified, all retailers are included.
Accepted values: list of
Writeable? N / Nullable? Y |
|
|
|
Includes only SKUs modified after the specified time. Must be within the last 18 hours; otherwise, a full export is required.
Format:
Writeable? N / Nullable? Y |
|
|
list
|
Optional fields to include in the export. If not provided, those fields will return with
Accepted values:
Writeable? N / Nullable? Y |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
list
|
List of required seller pairs
Parameters:
Writeable? N / Nullable? N |
|
|
|
Includes only SKUs modified after the specified time. Must be within the last 18 hours; otherwise, a full export is required.
Format:
Writeable? N / Nullable? Y |
|
|
list
|
Optional fields to include in the export. If not provided, those fields will return with
Accepted values:
Writeable? N / Nullable? Y |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
ID of the catalog creation request, to be used to retrieve its status and output (using other endpoints below - async) Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
enum |
Possible status of respective catalog creation
Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
enum |
Currency of the products in the catalog
Accepted values: 3-chars currency code (in
ISO-4217
; e.g.
Writeable? N / Nullable? Y |
|
|
integer |
Number of products available in the catalog (available when reach
Accepted values: int32 Writeable? N / Nullable? Y |
|
|
integer |
File size of catalog, in bytes (available when reach
Accepted values: int32 Writeable? N / Nullable? Y |
|
|
string |
MD5 checksum of catalog's content (available when reach
Accepted values: 32-char alpha-numeric strings Writeable? N / Nullable? Y |
|
|
timestamp |
Timestamp of catalog creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
string |
Optional informative message, for developer consumption Accepted values: string Writeable? N / Nullable? Y |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Product ID, defined by the retailer. Accepted values: case-insensitive, up to 50 characters, no quotation marks, ASCII characters Writeable? N / Nullable? N |
|
|
|
Product name, defined by the retailer. Accepted values: up to 500 characters Writeable? N / Nullable? N |
|
|
|
Product description, defined by the retailer. Accepted values: up to 5000 characters Writeable? N / Nullable? Y |
|
|
|
Product category, defined by the retailer. Accepted values: up to 1000 characters Writeable? N / Nullable? Y |
|
|
|
Category ID associated with the product, derived from the retailer catalog. Writeable? N / Nullable? Y |
|
|
|
Category associated with the product, derived from the Google Product Taxonomy . Writeable? N / Nullable? Y |
|
|
|
Brand ID of the product. For brand accounts, it is derived from the Universal Catalog. For retailer accounts, it is derived from the Retailer Catalog. Writeable? N / Nullable? N |
|
|
|
Brand name of the product; brands are standardized across retailers. Accepted values: up to 70 characters Writeable? N / Nullable? Y |
|
|
|
Seller ID(s) in the respective retailer’s catalog, used to filter down catalog items. Accepted values: case-insensitive, up to 50 characters, no quotation marks, ASCII characters Writeable? N / Nullable? Y |
|
|
|
Name of the seller associated with the
Accepted values: up to 200 characters Writeable? N / Nullable? Y |
|
|
|
Retailer ID that contains the product offer.
Accepted values: string of
Writeable? N / Nullable? N |
|
|
|
Name of the retailer that contains the product offer. Accepted values: up to 100 characters Writeable? N / Nullable? N |
|
|
|
Current product price in the respective retailer. Accepted values: up to 14 characters Writeable? N / Nullable? Y |
|
|
|
Flag indicating if the product is currently in stock.
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Minimum CPC (Cost-Per-Click) bid required for the product, as set by the retailer.
Any
Line Item
with this product must have its
Accepted values: > 0.0 Writeable? N / Nullable? Y |
|
|
|
Global Trade Item Number (GTIN), if available. Also known as EAN or UPC. Accepted values: up to 14 digits Writeable? N / Nullable? Y |
|
|
|
Manufacturer Part Number (MPN), if available. Accepted values: up to 70 characters Writeable? N / Nullable? Y |
|
|
|
HTTP URL of the product image, as provided by the retailer. Accepted values: up to 2000 characters Writeable? N / Nullable? N |
|
|
|
Timestamp of the last product update, in UTC.
Format:
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🟢
|
Success |
|
🔴
|
The indicated catalog is not available for retrieval, wait for a success status |
|
🔴
|
API user does not have the authorization to make requests to the account ID. For an authorization request, follow the steps |
# Catalog Source: https://developers.criteo.com/retail-media/docs/catalogs A catalog is a snapshot of all catalog products from the brands and retailers associated with an account, typically updated once a day. Each account has a single catalog listing all the products that the account is eligible to promote.
## What's next * [Catalog Endpoints](/retail-media/docs/catalog-endpoints) # Category Search Source: https://developers.criteo.com/retail-media/docs/category-search ## Introduction The `Category Search` endpoint enables you to explore and discover available product categories within a retailer's hierarchical taxonomy structure. Product categories allow retailers to create a hierarchical structure that helps narrow down products into unique groups or subgroups based on shared characteristics. This endpoint provides the ability to see what categories are available to serve against a retailer's inventory, making it an essential tool for understanding targeting options and campaign planning. Unlike recommendation endpoints, `Category Search` allows you to actively explore the retailer's category structure through flexible search parameters. You can search for categories using category IDs to find specific categories and their relationships, or use text substring matching to discover categories by name. The endpoint supports pagination for large result sets, making it easy to browse through extensive category hierarchies efficiently. This functionality is particularly valuable for **campaign setup**, **category discovery**, and **understanding the breadth of targeting options available within a retailer's ecosystem**. *** ## Endpoint
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Searches for available categories within a retailer's taxonomy |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Unique identifier for the retailer.
Found using the
Required in URL path. Writable? N / Nullable? N |
|
|
|
Array of category ID strings for search filtering. Must be positive integer strings. Writable? Y / Nullable? Y |
|
|
|
Text string to search for in category names. Used for category name filtering. Writable? Y / Nullable? Y |
|
|
|
Pagination offset for search results.
Default:
Query parameter. Writable? Y / Nullable? Y |
|
|
|
Maximum number of results to return.
Default:
Query parameter. Writable? Y / Nullable? Y |
|
Code |
Meaning |
Troubleshooting Hint |
|---|---|---|
|
🟢 200 |
Success |
Request processed successfully with pagination metadata |
|
🔴 400 |
Bad Request |
Check that
|
|
🔴 403 |
Forbidden |
Verify authorization and retailer access permissions |
# Overview Source: https://developers.criteo.com/retail-media/docs/demand-side-analytics-overview ## Before Starting The following information is important to know regarding Demand Side Analytics. ### Asynchronous Workflow `POST /reports/performance`, `POST /reports/missed-opportunities`, and `POST /reports/attributed-transactions` are all **asynchronous**: you submit a request, poll the returned `reportId` for status, and download the output once processing succeeds. 1. **Submit** the report request — a successful call returns `200 OK` with a `reportId` and a `status` of `pending`. 2. **Poll for status** at `GET /reports/{reportId}/status` until `status` is `success` or `failure`. 3. **Download the output** at `GET /reports/{reportId}/output` once `status` is `success`.
|
OAuth Method |
Rate limit |
Rate limit applies at level |
|---|---|---|
|
250 calls per minute for default endpoints 40 calls per minute for reporting endpoints |
Application level |
|
|
10 calls per minute |
Account |
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Request a fill rate report creation |
|
POST |
|
Request an unfilled reasons report |
|
GET |
|
Get status of a specific report |
|
GET |
|
Download output of a specific report |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
list\\ |
Supply Account IDs to pull results for Accepted values: array of strings/int64 Writable? N / Nullable? N |
|
|
list\\ |
An array of strings used to define which dimensions to see in the report Accepted values: refer to Metrics and Dimensions for the complete list of supported dimensions Writable? N / Nullable? N |
|
|
list\\ |
An array of strings used to define which metrics to see in the report Accepted values: refer to Metrics and Dimensions for the complete list of supported metrics Writable? N / Nullable? N |
|
|
date |
Start date of the report (inclusive)
Accepted values:
Writable? N / Nullable? N |
|
|
date |
End date of the report (inclusive)
Accepted values:
Writable? N / Nullable? N |
|
|
string |
Time zone to consider in the metrics calculation,
Accepted values: IANA (TZ database) time zones (example:
Default:
Writable? N / Nullable? Y |
|
|
enum |
The format type the report should return results
Accepted values:
Default:
Writable? N / Nullable? N |
|
|
enum |
The ad server responsible for rending the ad on the retailer site.
Accepted values:
|
|
Response |
Description |
|---|---|
|
🟢
|
Call executed with success |
|
🔴
|
Common Validation Errors:
|
|
🔴
|
|
## What's next * [Metrics & Dimensions (Fill Rate Report)](/retail-media/docs/metrics-dimensions-fill-rate-report) # Is Criteo Retail Media API for you? Source: https://developers.criteo.com/retail-media/docs/is-criteo-api-for-you
|
Verb |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Retrieve a Keywords Approval report to the specific supply account, with a count of keywords in review state at line-item |
|
GET |
|
Retrieve a set of all keywords in review state for the specific line-item |
|
POST |
|
Review keyword(s) for the specific line-item |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Line Item ID, respective to the amount of keywords in review Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Line Item name, respective to the amount of keywords in review Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
string |
Campaign ID, respective to the amount of keywords in review Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Campaign name, respective to the amount of keywords in review Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
string |
Account ID, respective to the amount of keywords in review Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Account name, respective to the amount of keywords in review Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
string |
Retailer ID, respective to the amount of keywords in review Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Retailer name, respective to the amount of keywords in review Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
integer |
Amount of keywords in review for the respective line-item
Accepted values:
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Line Item ID, respective to the amount of keywords in review Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
enum |
Status of the Keyword Review (only applicable for
Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
enum |
The matching algorithm to be used when comparing this keyword with shopper search phrases Accepted values:
Writeable? N / Nullable? N |
|
|
decimal |
The bid override for the positive keyword. The keyword will use the default line item bid if the value is
Accepted values: retailer's
Default:
Writeable? Y / Nullable? Y |
|
|
object |
Keywords supplied by the user matching this normalized keyword phrase binned by match type (see examples below) Parameters:
Writeable? Y / Nullable? Y |
|
|
timestamp |
Timestamp the keyword was created in the line-item (or recommended to line-item)
Accepted values:
Writeable? N / Nullable? N |
|
|
timestamp |
Last timestamp the keyword was updated in the line-item (or recommended to line-item)
Accepted values:
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
list
|
List of object pairs made of
Parameters:
Writeable? N / Nullable? N |
|
|
enum |
Normalized keyword for approval review
Accepted values: string keywords returned from previous endpoint (in
Writeable? N / Nullable? N |
|
|
enum |
Approval result of the Keyword Review Accepted values:
Writeable? N / Nullable? N |
## **Responses**
|
Response |
Title |
Detail |
Troubleshooting |
|---|---|---|---|
|
🟢
|
Call executed with success |
||
|
🟢
|
Entity request created with success |
||
|
🔴
|
Keyword Error |
One or more keywords given are not found on this line item |
Double-check the value of the keyword informed in the Review request; it should contain only existing keywords with
|
|
🔴
|
Model validation error |
Error converting value "xyz" to type 'Criteo.RetailMedia.
|
Value "xyz" provided is not a valid value for that respective parameter. Check the error details for more information |
|
🔴
|
Forbidden |
The account ID provided is not suitable for those endpoints (only supply accounts), the account is not included in the consent from the API app or the API app doesn't have Manage access to the Campaign domain/scope. Review the Types of Permissions in Authorization Requests |
## What's next * [Bid Multipliers](/retail-media/docs/bid-multipliers) * [Budget Overrides](/retail-media/docs/budget-overrides) * [Minimum Bid](/retail-media/docs/minimum-bid) # Keywords Source: https://developers.criteo.com/retail-media/docs/keywords ## Introduction
|
Verb |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Retrieve a set of positive and negative keywords for a line item |
|
GET |
|
Retrieve a collection of recommended keywords for a line item |
|
POST |
|
Add or remove keywords from a line item |
|
POST |
|
Set a bid override at keyword level |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Line Item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
object |
Keywords structure, indexed by normalized keyword phrases each of them containing structure of:
|
|
|
enum |
Matching algorithm type to be used when comparing this keyword with shopper search phrases. Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
enum |
Status of Keyword review, only applicable for
Keywords not reviewed by the automatic keyword service will be reviewed and approved by the retailer. Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
decimal |
The bid override for the positive keyword. The keyword will use the default line item bid if the value is
Accepted values: retailer's
Default:
Writeable? Y / Nullable? Y |
|
|
boolean |
Control flag to add or remove the keyword from the line-item
Accepted values:
Writeable? N / Nullable? N |
|
|
object |
Keywords structure associated with line-item containing normalized keyword phrases and organized by match type. Parameters:
|
|
|
string |
Raw text of the keyword to be added or removed Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
timestamp |
Timestamp when keyword was configured in the line-item (or recommended to line-item)
Accepted values:
Writeable? N / Nullable? N |
|
|
timestamp |
Timestamp when keyword was last modified in the line-item (or recommended to line-item)
Accepted values:
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🔵
|
Call completed with success |
|
🔵
|
|
|
🔴
|
Setting a bid for a positive keyword that doesn't exist on the line item. Error Message
Setting a keyword bid above the line-item
Error Message
Setting a keyword bid below the retailer
Error Message
|
## What's next * [Keyword Review](/retail-media/docs/keyword-review) # Line Items Source: https://developers.criteo.com/retail-media/docs/line-items ## Overview Each campaign consists of one or more line items. You can only run ads after creating a campaign and at least one line item. A line item allows you to select the products and the retailer where you'd like to advertise. Each line item can include multiple featured products but is restricted to a single retailer. To advertise across multiple retailers, you must create separate line items for each. Several settings are available to help you manage your budget and optimize ad delivery effectively. With the Criteo API, you can: * Manage your retail media line items * Configure line items, including budgets, flight dates, bids (for Onsite Sponsored Products), and targeting options (for Preferred Deals) * Retrieve products from your product catalog to advertise ### Line Item Settings
## What's next * [Line Items Endpoints](/retail-media/docs/line-items-endpoints) * [Promoted Products](/retail-media/docs/promoted-products) * [Recommended Keywords](/retail-media/docs/recommended-keywords) * [Recommended Categories](/retail-media/docs/recommended-categories) * [Category Search](/retail-media/docs/categories) # Line Items Endpoints Source: https://developers.criteo.com/retail-media/docs/line-items-endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Retrieve all line items associated with a specific account. |
|
GET |
|
Retrieve details of a specific line item. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Line item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Line item name, must be unique within a campaign Accepted values: up to 255-chars string Writeable? Y / Nullable? N |
|
|
string |
Campaign ID, in which the respective line item belongs Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
enum |
Campaign type
Accepted values:
Writeable? Y / Nullable? N |
|
|
string |
Retailer ID, in which the respective line item serves ad on Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
date |
Start date of the line item, in the Account timezone; used to schedule its activation and start serving ads. To understand the conditions that will cause a status to change, check out Campaign & Line Item Status
Accepted values:
Writeable? Y / Nullable? N |
|
|
date |
End date of the line item, in the Account timezone; serves ads indefinitely if omitted or set to
A timestamp can be included as well if the line item is desired to end at a certain time of day
Accepted values:
Default: if
Writeable? Y / Nullable? Y |
|
|
decimal |
Line item lifetime spend cap, uncapped if omitted or set to
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
decimal |
Budget amount the line item has already spent
Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
decimal |
Budget amount the line item has remaining until cap is hit;
Accepted values: 0 ≤
Default:
Writeable? N / Nullable? Y |
|
|
enum |
Line item status; can only be updated by a user to
Accepted values:
Writeable? Y / Nullable? N |
|
|
timestamp |
Timestamp of line item creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
timestamp |
Timestamp of last line item update, in UTC
Accepted values:
Default: same as
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🟢
|
Call completed successfully. The specified line item details are returned. |
|
🔴
|
API user is not authorized to make requests for the account ID. To request authorization, follow the steps. |
|
🔴
|
Line item ID not found. Ensure the
is correct and exists. |
## What's next * [Promoted Products](/retail-media/docs/promoted-products) * [Recommended Categories](/retail-media/docs/recommended-categories) * [Recommended Keywords](/retail-media/docs/recommended-keywords) * [Category Search](/retail-media/docs/categories) # Metrics and Dimensions (SSP) Source: https://developers.criteo.com/retail-media/docs/metrics-and-dimensions-ssp ## Introduction In this page you will find all the metrics and dimensions that are currently support with the [Revenue Report](/retail-media/docs/revenue-report-ssp). Please note that many of the metrics and dimensions listed here are currently supported only through the API. *** ## Dimensions
|
Dimensions |
Description |
|---|---|
|
|
The date of when reported activity took place occurred |
|
|
The hour of the day when rendered ad received an event |
|
|
The associated account that is connected to the supply or demand account |
|
|
The computed and unique identifier of the supply or demand account |
|
|
The supply or demand account name |
|
|
The account type of the reported activity. Options will include:
|
|
|
The advertiser account type where the ad activity originated from. Options includes:
|
|
|
The computed unique campaign identifier of the demand or supply account that generated the activity |
|
|
The campaign name of the demand or supply account that generated the activity |
|
|
The campaign type available. Available options are
|
|
|
The start date set for the campaign |
|
|
The end date set for campaign |
|
|
The computed unique identifier of a line-item |
|
|
The line-item name provided by the advertiser |
|
|
The start date set for the line-item |
|
|
The end date set for the line-item |
|
|
The status of the line-item associated with the selected dimension, such as the date or hour indicating of when the event took place. |
|
|
The retailer ID that is associated with the report activities . This will be the same
|
|
|
The retailer name that is associated to the report activity. |
|
|
The brand ID provided by the retailer brand ID associated with the advertised SKU |
|
|
The retailer brand name associated with the advertised SKU |
|
|
The id of the placement where the ad creative was displayed. |
|
|
The name of the placement where the ad creative was displayed. |
|
|
The page type where the ad was rendered |
|
|
The environment where the ad was rendered on. Options will include web, mobile and app |
|
|
The source of where activities originated from. Options will include
|
|
|
The campaign buying strategy. Options will include
|
|
|
Sales channel the attributed purchase was made through. Available options are:
|
|
|
The lookback click and view attribution window of the requested report. The attribution window is based on the parameters selected in the report API request. The
Post-Click (C) lookback window none, 7, 14, 30 days Post-view (V) lookback window none, 1, 7, 14, 30 days |
|
|
The type of ad engagement the sale was attributed to. Available options will include
|
|
|
Keyword or phrase used to land on the search page where an ad creative rendered. |
|
|
Attribution rule used to match the impression or click to a sale. Available options are:
|
|
|
Advertised product ID; this references the same product ID of the retailer Catalogs |
|
|
Advertised product name |
|
|
Advertised product GTIN |
|
|
Advertised product MPN |
|
|
The retailer defined category of the page where ads are rendered |
|
|
The retailer category provides the type of product the SKU belongs to. This fields provides the id of that product type |
|
|
The name of that product type |
|
|
The category breadcrumb of the product using retailer product taxonomies (L1, L2 L3 etc.). This is for analysis where SKUs are present in the displays |
|
|
The ID SKU's taxonomy. The revenue report provides the option to select level 1 through level 7.
ℹ️
Note
: SKUs will normally have at least the primary sku taxonomy (L1). All following levels are considered additional taxonomies. If a SKU does not have an additional taxonomy level, the report will default to
|
|
|
The name SKU's taxonomy. If a SKU does not have an additional taxonomy level, the report will default to
|
|
|
The conquesting ad strategy used with the keywords. Output values of this dimension includes:
|
|
Dimensions |
Description |
|---|---|
|
|
the total count of campaigns associated with the selected report dimension. |
|
|
The total count of line-items associated with the selected report dimension. |
|
|
The total count of skus associated with the selected report dimension. |
|
|
The total price of each SKU unit.
|
|
|
The count of unique ad calls on a retailer network. Use this metric when referencing to dimensions that relates to itself to receive a more comprehensive data. Using dimensions such as
|
|
|
An impression represents each time an ad renders on a page, regardless of clicks or views. An impression for a Sponsored Product ad is when the sponsored SKU renders on the page (the product being the ad). An impression for a Commerce Display ad is when the entire banner (creative + product) renders on the page. An impression for a Display banner ad is when the creative banner renders on the page. |
|
|
Total count of the click events that occur when a user clicks a product in a placement |
|
|
Total count of the click events that occur when a user clicks a placement |
|
|
The total count of all click events
|
|
|
The total attributed revenue from product sales |
|
|
The total attributed product units sold |
|
|
Sales revenue attributed to a click or impression of all the ads that appeared on a page within the chosen attribution window (specified at the campaign level) but were not determined to be the
|
|
|
The number of events that occurred that helped generated a sale. Assisted units are excluded from
|
|
|
The total amount of sponsored products revenue generated on the set date, not including sponsorships. |
|
|
The total amount of onsite display revenue generated on the set date, not including sponsorships. |
|
|
The total amount of sponsored products revenue generated on the set date, not including sponsorships. |
|
|
The total amount of onsite display revenue generated on the set date, not including sponsorships. |
|
|
The total revenue generated on the set date. The
|
|
|
The total amount of attributed orders/transactions |
|
|
The percentage of shoppers who clicked an ad rendered on a page. Product and Product Category Report Types
All other report types
|
|
|
The number of conversion generated by the visitors to the retailer site.
|
|
|
Average cost-per-click calculated by dividing openAuctionRevenue / clicks or preferredDealsRevenue / clicks |
|
|
Average cost per mille calculated by diving
|
|
|
Return-on-ad-spend (ROAS), calculated by dividing
|
|
|
The total spend paid by the brand |
|
|
The total revenue from brand spend for the retailer |
|
|
The number of distinct shoppers exposed to an ad within the reporting period. Each shopper is counted once using the retailer cookie ID.
Criteo uses retailer cookie IDs to identify users across sessions on the same device. Each ID can last up to a year, provided the user does not clear their cookies. |
|
|
An average representing how often an impression has been shown to the same user |
|
Key-Values |
Data Type |
Description |
|---|---|---|
|
|
|
The number of times at least 50% of the video ad appeared for at least 2 seconds (MRC standard). |
|
|
|
The number of times one of your video ads started playing. |
|
|
|
The number of times one of your videos played to at least 25% of its duration. |
|
|
|
The number of times one of your videos played to at least 50% of its duration. |
|
|
|
The number of times one of your videos played to at least 75% of its duration. |
|
|
|
The number of times one of your videos played to 100% of its duration. |
|
|
|
The average played percentage of a started video. Formula: Sum of Quartiles x 0.25 / (4 x Video starts) |
|
|
|
The percentage of started videos that played for their entire duration. Formula: Number of videos that played to completion / Total number of videos started \* 100 |
|
|
|
The percentage of videos printed that started playing. Formula: Video Starts / Placement Impressions |
|
|
|
The average played percentage of a started video. Formula: Sum of Quartiles x 0.25 / (4 x Video starts) |
|
|
|
The number of times users clicked the “mute” button on your video. |
|
|
|
The number of times users clicked the “unmute” button on your video. |
|
|
|
The number of times users activated the resume control after the creative had been stopped and paused. |
|
|
|
The number of times users activated the pause control on the video. |
|
|
|
The percentage of video ads that were considered viewable. At least 50% of the ad’s pixels must be visible on the screen for at least two continuous seconds (MRC standard). Requires OMID support. Formula: Viewable Impressions / Placement Impressions |
# Metrics & Dimensions (Fill Rate Report) Source: https://developers.criteo.com/retail-media/docs/metrics-dimensions-fill-rate-report ## Introduction In this page, you will find all the metrics and dimensions that are currently supported in the reports for Supply Side accounts: * [Revenue Report](/retail-media/docs/revenue-report-ssp): provides attributed performance data from campaigns. * [Fill Rate Report](/retail-media/docs/fill-rate-report): provides summary of placement opportunities and impression filled and covered in retailer(s) inventory.
|
Dimensions |
Description |
|---|---|
|
|
The date of when reported activity took place occurred |
|
|
The retailer ID that is associated with the report activities. This will be the same
|
|
|
The retailer name that is associated to the report activity. |
|
|
The environment where the ad was rendered on. Options will include web, mobile and app |
|
|
The page type where the ad was rendered |
|
|
The
|
|
|
The name of the placement where the ad creative was displayed. |
|
|
The ad server where the ad was rendered on.
Value:
|
|
|
The retailer category provides the type of product the SKU belongs to. This field provides the ID of that product type. |
|
|
The name of that product type |
|
|
The category breadcrumb of the retailer page where ads are rendered Example: "*beauty and grooming > fragrances > deodorants > sprays > jive sprays > jive moon dream 9 piece body spray - for men & women*" |
|
Dimensions |
Description |
|---|---|
|
|
The number of available placements that were available to fill, including non-deliverable and deliverable placements. |
|
|
The total count of all click events
Formula
:
|
|
|
The number of covered placements divided by the number of deliverable placements |
|
|
A placement with candidates where Criteo has provided SKUs or line-items in the ad response |
|
|
Average cost-per-click
Formula
:
|
|
|
Average cost per *mille*, calculated by:
Formula
:
|
|
|
Available placement that the retailer allowed Criteo to run an auction for |
|
|
The number of times a deliverable placement on a page was populated with an ad (even if the impression was not viewable). Calculated by dividing the placement impressions by deliverable placements.
Formula
:
|
|
|
An impression represents each time an ad renders on a page, regardless of clicks or views. An impression for a Sponsored Product ad is when the sponsored SKU renders on the page (the product being the ad). An impression for a Commerce Display ad is when the entire banner (creative + product) renders on the page. An impression for a display banner ad is when the creative banner renders on the page. |
|
|
The total revenue from brand spend for the retailer |
|
|
A non-deliverable placement is a placement against which Criteo is not allowed by the retailer to run an auction. |
|
|
The count of unique ad calls on a retailer network. Use this metric when referencing to dimensions that relates to itself to receive a more comprehensive data. Using dimensions such as
|
|
|
Total count of the click events that occur when a user clicks a placement |
|
|
The number of placement impressions. |
|
|
The percentage of shoppers who clicked an ad placement rendered on a page
Formula
: (
|
|
|
The total revenue generated by placement impressions of CPM ads |
|
|
A placement with candidates is a placement for which Criteo is allowed by the retailer to run an auction and has sufficient information and demand to run it. |
|
|
Total count of the click events that occur when a user clicks a product in a placement |
|
|
The total revenue generated by product clicks of CPC ads |
|
|
The number of filled product impressions |
|
|
The number of clicks divided by the number of product impressions
Formula
:
|
|
|
The total revenue generated on the set date. The
|
|
|
The number of unfilled placements |
|
|
The total spend paid by the brand |
|
Reason |
Definition |
|---|---|
|
Uncovered |
|
|
|
The number of available ad placements that did not serve any impressions. |
|
|
There is not enough line items eligible to the placement for run of site placements. |
|
|
Ads returned to the retailer, but on placements that the retailer rarely paints. If a placement has a painted rate of less than 1% over the last 7 days, it can be considered as broken. |
|
|
Filtering reasons are the set of reasons for which line items can and will be excluded from pre-auctions, which decreases the number of ad opportunities overall. Filtering reasons may be of technical, supply, or demand nature (out of stock, dayparting, audience targeting, capping…) |
|
|
Available opportunities without candidate campaigns, that happen on branded keywords on retailers that disabled conquesting (on that particular placement). No demand on branded keyword conquesting disabled |
|
|
Available opportunities without candidate campaigns, that happen on branded keywords on retailers that enabled conquesting (on that particular placement) |
|
|
Ad placements available on general (non-branded) inventory, but no campaigns are set up to use them |
|
|
Ads returned to the retailer but not displayed (on placements that aren't broken). |
|
|
Ad placements on keywords that the keyword model cannot categorize. |
|
Undeliverable |
|
|
|
Ad placements for opt-out users that are not delivering because you have not enabled ads for these users |
|
|
Ad placements on pages where you have blocked Criteo from running auctions (e.g., some categories on which you do not want any ads to be served) |
|
|
Ad placements where the page does not have enough organic results to display ads. For example, if an ad is meant to appear on line 5 but fewer than 5 lines of products exist. |
|
|
These are ad placements that are still in testing and not fully enabled. |
|
|
Ad placements on category and merchandising pages that aren't deliverable because their category keys are missing from the retailer’s product feed. |
|
|
Product pages where items can't be identified in the retailer's product feed. |
## What's next * [Fill Rate Report](/retail-media/docs/fill-rate-report) # Minimum Bid Source: https://developers.criteo.com/retail-media/docs/minimum-bid ## Introduction 1. An [Onsite Sponsored Products](/retail-media/docs/onsite-sponsored-products) line item holds promoted products to advertise on a single retailer. 2. Line items have bid settings, start & end dates, and optional budgeting & pacing controls. 3. Target & maximum bid settings must respect minimum bid (`minBid`), that can be set at product SKU level, to start delivering ads 4. Products SKU IDs are available through [Catalog](/retail-media/docs/catalogs) endpoints. *** ## Endpoints
|
Verb |
Endpoint |
Description |
|---|---|---|
|
|
|
Search for min bid CPC defined by collection of SKU IDs |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Retailer ID where the line item will serve ads on Accepted values: int64 Writeable? N / Nullable? N |
|
|
list
|
List of SKU IDs in which the minimum bid is requested (usually, the SKUs promoted by the line item). Values are available through Catalog endpoints
Accepted values: at least, an empty list
Writeable? N / Nullable? N |
|
|
string |
SKU ID respective to the
Accepted values: SKU IDs from catalog Writeable? N / Nullable? N |
|
|
decimal |
Overall minimum bid resulted from the list of SKUs requested, that the line item should respect to, effectively, deliver ads
Acceptable values: at least
Writeable? N / Nullable? N |
|
|
decimal |
Minimum bid for the respective SKU
Acceptable values: at least
Writeable? N / Nullable? N |
|
Response |
Description |
|---|---|
|
🟢
|
Call executed with success |
|
🔴
|
json-serialization-error Required attribute missing or with unexpected format in request's body |
|
🔴
|
Not Found Retailer ID informed in request's path was not found |
## What's next * [Demand Side Analytics (DSP)](/retail-media/docs/analytics) * [Supply Side Analytics (SSP)](/retail-media/docs/supply-side-reporting-ssp) # Missed Opportunities Report Source: https://developers.criteo.com/retail-media/docs/missed-opportunities-report POST /reports/missed-opportunities — diagnose budget cap-out and estimate missed delivery for Retail Media DSP campaigns. This endpoint enables Retail Media DSP partners to diagnose budget cap-out and estimate missed delivery for their campaigns and line items. Cap-out occurs when a line item exhausts its daily budget before the day ends, causing it to stop participating in eligible auctions. Missed traffic is reported for any line item that did not participate in all eligible auctions during the day. The response is aggregated — one row per day per line item (or per combination of dimensions you specify). All metrics relate to delivery shortfalls; no performance metrics (impressions served, clicks, revenue) are included. For performance metrics, use [`POST /reports/performance`](/retail-media/docs/performance-report). **Primary audience:** Engineers and ops teams diagnosing delivery shortfalls. Not a campaign performance reporting surface. The endpoint supports asynchronous report generation. Submit a request, poll for status, and download the output when ready. *** ## Request ```http theme={null} POST /2026-07/retail-media/reports/missed-opportunities ``` ### Required fields `startDate`, `endDate`, `filters`, `dimensions`, and `metrics` are all required. `filters` must contain exactly one scope filter (`filters.accountIds[]`, `filters.campaignIds[]`, or `filters.lineItemIds[]`). | Field | Type | Description | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | | `startDate` | string | Inclusive report start date. ISO 8601 date (`YYYY-MM-DD`). | | `endDate` | string | Inclusive report end date. ISO 8601 date (`YYYY-MM-DD`). Must be ≥ `startDate`. Dates are interpreted in UTC. | | `filters` | object | Required. Must contain exactly one of the scope filters below. | | `filters.accountIds[]` | array of strings | Scope to all line items under this account. Mutually exclusive with `campaignIds` and `lineItemIds`. | | `filters.campaignIds[]` | array of strings | Scope to all line items under this campaign. Mutually exclusive with `accountIds` and `lineItemIds`. | | `filters.lineItemIds[]` | array of strings | Scope to this line item. Mutually exclusive with `accountIds` and `campaignIds`. | | `dimensions` | array of strings | Required. Output grouping fields. See [Dimensions](#dimensions) below. | | `metrics` | array of strings | Required. Output measure fields. See [Metrics](#metrics) below. | ### Optional fields | Field | Type | Default | Description | | ------------------------- | ---------------- | -------------- | ---------------------------------------------------------------- | | `format` | string | `json-compact` | Output format: `json`, `json-compact`, `json-newline`, or `csv`. | | `filters.salesChannels[]` | array of strings | — | Filter by sales channel. | | `filters.mediaTypes[]` | array of strings | — | Filter by media type. | ### Example request ```http theme={null} POST /2026-07/retail-media/reports/missed-opportunities Authorization: Bearer {token} Content-Type: application/json { "data": { "type": "AsyncMissedOpportunitiesReport", "attributes": { "startDate": "2026-05-01", "endDate": "2026-05-07", "filters": { "lineItemIds": ["301234567890123457"] }, "dimensions": ["date", "lineItemId", "lineItemName"], "metrics": ["missedTraffic", "missedSpend", "capoutHour"] } } } ``` *** ## Response A successful request returns `200 OK` with a `reportId`: ```json theme={null} { "data": { "type": "StatusResponse", "id": "4ddbf658-e588-41b7-bd21-82b0f93bec32", "attributes": { "status": "pending", "rowCount": 0, "fileSizeBytes": 0, "md5CheckSum": null, "createdAt": "2026-07-28T13:37:21.000Z", "expiresAt": null, "message": null, "id": "4ddbf658-e588-41b7-bd21-82b0f93bec32" } } } ``` Poll for status until `status` is `success` or `failure`: ```http theme={null} GET /2026-07/retail-media/reports/{reportId}/status Authorization: Bearer {token} ``` ```json theme={null} { "data": { "type": "StatusResponse", "id": "4ddbf658-e588-41b7-bd21-82b0f93bec32", "attributes": { "status": "success", "rowCount": 7, "fileSizeBytes": 937, "md5CheckSum": "a7113a91e30cc0b0de3827703280fe8f", "createdAt": "2026-07-28T13:37:21.000Z", "expiresAt": "2026-08-04T13:37:22.000Z", "message": "rows_count=7", "id": "4ddbf658-e588-41b7-bd21-82b0f93bec32" } } } ``` Download the output when status is `success`: ```http theme={null} GET /2026-07/retail-media/reports/{reportId}/output Authorization: Bearer {token} ``` ```json theme={null} { "columns": ["date", "lineItemId", "lineItemName", "missedTraffic", "missedSpend", "capoutHour"], "data": [ ["2026-05-01", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.0, 0.0, "No cap-out"], ["2026-05-02", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.148558, 2676.70, "20:00"], ["2026-05-03", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.155921, 2813.52, "20:00"], ["2026-05-04", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.099693, 1686.55, "21:00"], ["2026-05-05", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.01672, 251.76, "23:00"], ["2026-05-06", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.001905, 29.17, "23:00"], ["2026-05-07", "301234567890123457", "Spring Sale - Kitchen Search - Broad", 0.014384, 222.97, "23:00"] ], "rows": 7 } ``` Each row in the report output represents one day (or one combination of dimensions, if dimensions were specified). *** ## Response Codes For the full list of status and error codes for this endpoint — including `404` (report not found) and `410` (report expired) — see [Response Codes](/retail-media/docs/demand-side-analytics-overview#response-codes) in the Overview. *** ## Metrics Select metrics using the `metrics[]` array in your request. `metrics` is required. | Metric | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capoutHour` | Hour of the day when the line item exhausted its daily budget, on average, formatted as `HH:00` (e.g. `14:00` means budget was exhausted around 2pm on average). Returns the string `"No cap-out"` — not `null` or a numeric hour — for a day where the line item didn't cap out. | | `missedClicks` | Estimated clicks lost due to reduced auction participation. | | `missedImpressions` | Estimated impressions lost due to reduced auction participation. | | `missedSales` | Estimated revenue lost due to reduced auction participation, in the account's reporting currency. | | `missedSpend` | Estimated spend that would have occurred had the line item participated in all eligible auctions. | | `missedTraffic` | Percentage of the day's total eligible traffic the line item did not participate in. | | `daypartingScheduled` | Binary: whether dayparting was active at the time of the cap-out event. | | `totalSpend` | Total media spend for the line item. | | `roas` | Return on ad spend — revenue per unit of currency spent. | | `attributedSales` | Sales revenue attributed to the campaign per attribution settings. | | `impressions` | Impressions served. | | `clicks` | Clicks counted. | | `cpc` | Average cost per click. | | `cpm` | Average cost per 1,000 impressions. | | `ctr` | Click-through rate: clicks / impressions. | All "missed" estimates are modeled — they represent what the line item would have delivered had it participated in all eligible auctions. *** ## Dimensions Select grouping dimensions using the `dimensions[]` array in your request. `dimensions` is required. | Dimension | Description | | -------------- | ----------------------------------------- | | `date` | Date events occurred. | | `accountId` | Account ID. | | `accountName` | Account name. | | `campaignId` | Campaign ID. | | `campaignName` | Campaign name. | | `lineItemId` | Line item ID. | | `lineItemName` | Line item name. | | `retailerId` | Retailer ID where the line item served. | | `retailerName` | Retailer name where the line item served. | | `buyType` | Buy type of the line item. | | `bidStrategy` | Bid strategy of the line item. | *** ## Data Retention This endpoint supports a lookback window of up to **3 years** (36 months). A request with a `startDate` older than that returns `400 Bad Request` — `StartDate cannot be older than 3 years.` Separately, a single report may span at most **100 days** between `startDate` and `endDate`, regardless of whether you scope by account, campaign, or line item. *** ## Migrating from `reportType: capout` Replace your existing call on `/reports/campaigns` or `/reports/line-items` with a call to this endpoint. The underlying data is unchanged. **Endpoint change:** ``` POST /reports/campaigns → POST /reports/missed-opportunities POST /reports/line-items → POST /reports/missed-opportunities ``` **Request shape changes:** * Replace the top-level `accountId` / `campaignId` / `lineItemId` fields with a `filters` object containing `accountIds[]`, `campaignIds[]`, or `lineItemIds[]` arrays. * Add required `dimensions[]` and `metrics[]` arrays to select output columns. * `startDate` and `endDate` are now required (date-only `YYYY-MM-DD`; timestamps are rejected). * Remove `reportType: capout` — it is not accepted on this endpoint. **Metric renames:** | Old name | New name | | ------------------------- | -------------------------- | | `capoutMissedClicks` | `missedClicks` | | `capoutMissedImpressions` | `missedImpressions` | | `capoutMissedSales` | `missedSales` | | `capoutMissedSpend` | `missedSpend` | | `capoutMissedTraffic` | `missedTraffic` | | `capoutHour` | `capoutHour` *(unchanged)* | **Dimension changes:** `daypartingScheduled` has moved from a dimension to a metric in this endpoint. Add it to your `metrics[]` array instead of `dimensions[]`. # Onsite Sponsored Products Source: https://developers.criteo.com/retail-media/docs/onsite-sponsored-products ## Line Items Each campaign consists of one or several line items. With the Criteo Retail Media API, you can run an ad only after creating a campaign and, at least, one line item.
|
Match Type |
Negative keyword |
Ads won't show for |
Ads may show for |
|---|---|---|---|
|
Broad match |
Men's shoes |
Men shoes, Blue men’s shoes, Men's shoe size 9 |
Shoes, Boy’s shoes, Men’s basketball shoes |
|
Exact match |
Men’s shoes |
Men’s shoes, Mens shoes, Mens shoe |
Shoes, Blue men’s shoes, Mens shoe size 9 |
|
Submitted keyword match type |
Positive keyword |
Ads will show for |
Ads won’t show for |
|---|---|---|---|
|
Exact match |
Women's shoes |
Women's shoes, Womens shoes, Womens shoe |
Shoes, Blue women’s shoes, Womens shoe size 9 |
## What's next * [Onsite Sponsored Products Line Items](/retail-media/docs/onsite-sponsored-products-line-items) # Onsite Sponsored Products Line Items Source: https://developers.criteo.com/retail-media/docs/onsite-sponsored-products-line-items
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Get all auction line items from a specific campaign |
|
POST |
|
Create a new auction line item |
|
GET |
|
Get a specific auction line item |
|
PUT |
|
Update a specific auction line item |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Auction line item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Line item name, must be unique within the Campaign Accepted values: between 2 and 255-chars string Writeable? Y / Nullable? N |
|
|
string |
Campaign ID, in which the respective line item belongs and generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Retailer ID where the line item will serve ads on. For retailer-budgets campaigns, must match the campaign's
Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
date |
Start date of the line item, used to schedule its activation and start serving ads. To understand the conditions that will cause a status to change, check out Campaign & Line Item Status
ℹ️ This now supports datetime offset to define the desired time zone, in the format of
Accepted values:
Writeable? Y / Nullable? N |
|
|
date |
End date of the line item; serves ads indefinitely if omitted or set to
ℹ️ This now supports datetime offset to define the desired time zone, in the format of
Accepted values:
Default: if
Writeable? Y / Nullable? Y |
|
|
decimal |
Lifetime spend cap of line item (optional), uncapped if omitted or set to
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
decimal |
Budget amount the line item has already spent
Accepted values:
Default:
Writeable? N / Nullable? N |
|
|
decimal |
Amount the line item has remaining until cap is hit;
Accepted values: 0 ≤
Default:
Writeable? N / Nullable? Y |
|
|
decimal |
Amount the line item can spend per calendar month (optional), in the Account time zone. Omitting or setting to
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
decimal |
Amount the line item can spend per calendar day (optional), in the Account time zone. It resets each day; overwritten by calculation if
Accepted values:
Default:
Writeable? Y / Nullable? Y |
|
|
boolean |
To activate, either line item
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
enum |
Indicate whether Adaptive CPC is enabled or not
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
enum |
Bid algorithm optimizing for sales conversions, sales revenue or clicks
Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
bidStrategy decimal |
If optimizing for
ℹ️ Note:
Accepted values: at least the greatest value of
Default:
Writeable? Y / Nullable? Y |
|
|
decimal |
If optimizing for
ℹ️ Note:
Accepted values: at least
⚠️ Note: As of Writeable? Y / Nullable? Y |
|
|
enum |
Line item status; can only be updated by a user to
Accepted values:
Writeable? Y / Nullable? N |
|
|
object |
Settings allowing custom scheduling for serving ads serving, organized by a combination of
Accepted values: see below Writeable? Y / Nullable? Y |
|
|
enum |
Keyword strategy used to target users according to the promoted products appended in the line item and their competitors ℹ️ Note: "*Conquesting*" is not available for all retailers; when creating a new line item for those retailers, a validation error will return which can be avoided by omitting this attribute from the request Accepted values:
Default:
Writeable? Y / Nullable? N |
|
|
timestamp |
Timestamp of line item creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
timestamp |
Timestamp of last line item update, in UTC
Accepted values:
Default: same as
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
enum |
Day of the week or day type that the respective
Accepted values:
Writeable? Y / Nullable? N |
|
|
time |
Start time that the respective
ℹ️ This time value will be interpreted considering the time zone provided in the
Accepted values:
Writeable? Y / Nullable? N |
|
|
time |
End time that the respective
ℹ️ This time value will be interpreted considering the time zone provided in the
Accepted values:
Writeable? Y / Nullable? N |
|
Response |
Title |
Description |
|---|---|---|
|
🔵
|
Call completed with success |
|
|
🔵
|
Line item created with success |
|
|
🔴
|
Invalid
|
Cannot turn on
|
|
🔴
|
Conquesting not enabled |
|
|
🔴
|
|
|
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Request a partner billing report creation |
|
GET |
|
Get status of a specific report |
|
GET |
|
Download output of a specific report |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
list |
Account IDs (currently supports only Supply Account IDs) Accepted values: array of strings/int64 Writeable? N / Nullable? N |
|
|
list |
Retailer IDs Accepted values: array of strings/int64 Writeable? N / Nullable? N |
|
|
date |
Start date of the report (inclusive)
Accepted values:
Writeable? N / Nullable? N |
|
|
date |
End date of the report (inclusive)
Accepted values:
Writeable? N / Nullable? N |
|
|
enum |
The format type the report should return results
Accepted values:
Default:
Writeable? N / Nullable? N |
|
Response |
Title |
Detail |
Troubleshooting |
|---|---|---|---|
|
🟢
|
Call executed with success |
||
|
🟢
|
Report request created with success |
||
|
🔴
|
Validation error |
Invalid date range. Maximum allowed is 31 days. |
Review the
|
|
🔴
|
Model Validation error |
|
Review the value of respective field provided, ensuring it was informed with a valid format |
|
🔴
|
The scope Billing is missing |
The scope Billing is required to access this endpoint and is missing from the provided token |
The respective API app doesn't have access to the domain/scope Billing. Review the Types of Permissions in Authorization Requests |
|
🔴
|
Authorization error |
Resource access forbidden: all the accounts/retailers are not accessible. |
Review the Account/Retailer ID(s) provided in the report request |
## What's next * [PBR Metrics](/retail-media/docs/pbr-metrics) # PBR Metrics Source: https://developers.criteo.com/retail-media/docs/pbr-metrics ## Introduction In this page, you will find the definition and details of all metrics currently supported in the [Partner Billing Report](/retail-media/docs/partner-billing-report). *** ## Metrics
|
Dimensions |
Data Type |
Description |
|---|---|---|
|
|
string |
Account name |
|
|
string |
Account ID, generated by Criteo |
|
|
string |
Flag if report item is billable or not based on the non-billable settings |
|
|
string |
The category the account falls under, values can be:
|
|
|
string |
Retailer name tied to the account |
|
|
string |
Managed service or self-service
⚠️
Note
: if the
|
|
|
string |
The value should reflect either “Retailer” or “Criteo” is doing the billing |
|
|
string |
Account currency, in 3-chars code (in ISO-4217 ) |
|
|
string |
Indicates the source of account creation, distinguishing whether the account was created by a third-party partner working with Criteo; if so, the partner’s name is specified, otherwise,
|
|
|
integer |
|
|
|
string |
Balance ID associated with the account, generated by Criteo |
|
|
string |
Balance name
⚠️
Note
: if the
|
|
|
string |
Purchase order associated to the Balance
⚠️
Note
: if the
|
|
|
timestamp |
Start date of the Balance, in format
⚠️
Note
: if the
|
|
|
The payment option of the Private Market demand account at the balance level
⚠️
Note
: if the
|
|
|
|
string |
Campaign ID, generated by Criteo |
|
|
string |
Campaign name |
|
|
string |
Campaign type (⚠️ Campaigns eg:
|
|
|
string |
Campaign buying type (e.g. Auction, Preferred Deals, Sponsorship) |
|
|
string |
Line item ID, generated by Criteo |
|
|
string |
Line item name |
|
|
decimal |
Working media spend |
|
|
decimal |
Credit spend is the amount of credit applied in a given month to restore a working media budget that was originally impacted by bots, technical errors, or human errors. |
|
|
decimal |
Value add spend is the amount of free budget applied in a given month, typically granted to brands or agencies as an incentive to spend above a specific threshold, invest in new retailers, expand into new product categories, or test different formats and audiences. |
|
|
integer |
Amount of billable clicks recorded |
|
|
integer |
Amount of billable impressions recorded |
|
|
decimal |
Retailer's SSP fee amount |
|
|
decimal |
Managed service fee set at the supply account, which applies to the demand side of the supply account |
|
|
decimal |
Retailer's managed service fee amount |
|
|
decimal |
Retailer's offsite audience revenue before Criteo's take rate |
|
|
decimal |
Criteo's take rate from retailer offsite audience revenue |
|
|
string |
Timezone offset of the account |
|
|
decimal |
Retailer's sales enablement professional service fee amount |
|
|
decimal |
Retailer's self-service enablement professional service fee amount |
# Performance Report Source: https://developers.criteo.com/retail-media/docs/performance-report POST /reports/performance — flexible campaign performance reporting for Retail Media DSP partners. This endpoint enables Retail Media DSP partners to request flexible performance reporting across any level of granularity. Provide a scope filter under `filters` to define the data returned — the output granularity is then determined by the dimensions you include in the request. The endpoint supports asynchronous report generation and provides access to the full set of performance metrics and dimensions, including video, new-to-brand, and keyword data. Submit a request, poll for status, and download the output when ready. *** ## Request ```http theme={null} POST /2026-07/retail-media/reports/performance ``` ### Required fields `filters` (with exactly one scope filter), `startDate`, `endDate`, `metrics`, and `dimensions` are all required. Requests with no scope filter (or more than one) will return `400 Bad Request`. | Field | Type | Description | | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- | | `filters` | object | Required. Must contain exactly one of the scope filters below. | | `filters.accountIds[]` | array of strings | Scope the report to all campaigns under this account. Mutually exclusive with `campaignIds` and `lineItemIds`. | | `filters.campaignIds[]` | array of strings | Scope the report to all line items under this campaign. Mutually exclusive with `accountIds` and `lineItemIds`. | | `filters.lineItemIds[]` | array of strings | Scope the report to this line item. Mutually exclusive with `accountIds` and `campaignIds`. | | `startDate` | string | Start of the reporting period. ISO 8601 date (`YYYY-MM-DD`). | | `endDate` | string | End of the reporting period. ISO 8601 date (`YYYY-MM-DD`). | | `metrics` | array of strings | One or more metric names. See [Metrics](#metrics) below. | | `dimensions` | array of strings | One or more dimension names. See [Dimensions](#dimensions) below. | ### Optional fields | Field | Type | Default | Description | | -------------------------------- | ---------------- | -------------- | ----------------------------------------------------------------------------------------------- | | `timezone` | string | `UTC` | Timezone for date bucketing. IANA format (e.g. `America/New_York`). | | `format` | string | `json-compact` | Output format: `json`, `json-compact`, `json-newline`, or `csv`. | | `clickAttributionWindow` | string | — | Attribution window for click-based conversions: `none`, `7D`, `14D`, or `30D`. | | `viewAttributionWindow` | string | — | Attribution window for view-based conversions: `none`, `1D`, `7D`, `14D`, or `30D`. | | `clickMatchLevel` | string | — | Match level for click attribution. | | `viewMatchLevel` | string | — | Match level for view attribution. | | `filters.campaignTypes[]` | array of strings | — | Filter by campaign type. Values constrain eligible campaigns and may affect metric eligibility. | | `filters.salesChannels[]` | array of strings | — | Filter by sales channel. | | `filters.mediaTypes[]` | array of strings | — | Filter by media type. | | `filters.buyTypes[]` | array of strings | — | Filter by buy type. | | `filters.budgetModels[]` | array of strings | — | Filter by budget model. | | `filters.activationPlatforms[]` | array of strings | — | Filter by activation platform. | | `filters.searchTermTypes[]` | array of strings | — | Filter by search term type. | | `filters.searchTermTargetings[]` | array of strings | — | Filter by search term targeting strategy. | | `filters.targetedKeywordTypes[]` | array of strings | — | Filter by targeted keyword type. | ### Example request ```http theme={null} POST /2026-07/retail-media/reports/performance Authorization: Bearer {token} Content-Type: application/json { "data": { "type": "AsyncPerformanceReport", "attributes": { "filters": { "campaignIds": ["301234567890123456"] }, "startDate": "2026-05-01", "endDate": "2026-05-07", "timezone": "America/New_York", "metrics": ["impressions", "clicks", "spend", "roas"], "dimensions": ["date", "campaignName", "lineItemName"] } } } ``` *** ## Response A successful request returns `200 OK` with a `reportId`. Use this ID to poll for status and retrieve the output. ```json theme={null} { "data": { "type": "StatusResponse", "id": "c378da57-960e-4ce4-a297-770f9512af56", "attributes": { "status": "pending", "rowCount": 0, "fileSizeBytes": 0, "md5CheckSum": null, "createdAt": "2026-07-28T13:37:17.000Z", "expiresAt": null, "message": null, "id": "c378da57-960e-4ce4-a297-770f9512af56" } } } ``` Once the report finishes processing, the status response is fully populated: ```json theme={null} { "data": { "type": "StatusResponse", "id": "c378da57-960e-4ce4-a297-770f9512af56", "attributes": { "status": "success", "rowCount": 7, "fileSizeBytes": 1125, "md5CheckSum": "cb448a82ac773d48672cdf30c4fae9de", "createdAt": "2026-07-28T13:37:17.000Z", "expiresAt": "2026-08-04T13:37:18.000Z", "message": "rows_count=7", "id": "c378da57-960e-4ce4-a297-770f9512af56" } } } ``` **Poll for status** until `status` is `success` or `failure`: ```http theme={null} GET /2026-07/retail-media/reports/{reportId}/status Authorization: Bearer {token} ``` **Download the output** when status is `success`: ```http theme={null} GET /2026-07/retail-media/reports/{reportId}/output Authorization: Bearer {token} ``` With no `format` specified, the output defaults to `json-compact` — a `columns`/`data` array shape rather than an array of row objects: ```json theme={null} { "columns": ["date", "campaignName", "lineItemName", "impressions", "clicks", "spend", "roas"], "data": [ ["2026-05-01", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 2176050, 6461, 15506.65, 22.14], ["2026-05-02", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 1902829, 6396, 15295.60, 20.36], ["2026-05-03", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 2061778, 6782, 16234.17, 21.70], ["2026-05-04", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 1965894, 6287, 15034.17, 24.13], ["2026-05-05", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 1968091, 6261, 12959.99, 30.44], ["2026-05-06", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 2075084, 6648, 14762.81, 25.46], ["2026-05-07", "Spring Sale - Kitchen Search", "Spring Sale - Kitchen Search - Broad", 2089278, 6551, 15127.54, 20.34] ], "rows": 7 } ``` *** ## Response Codes For the full list of status and error codes for this endpoint — including `404` (report not found) and `410` (report expired) — see [Response Codes](/retail-media/docs/demand-side-analytics-overview#response-codes) in the Overview. *** ## Metrics
|
Method |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Retrieve all products associated with a specific line item. |
|
POST |
|
Add products to a specific line item or update their bid override. |
|
POST |
|
Remove products from a specific line item. |
|
POST |
|
Pause products on a specific line item, preventing them from being advertised. |
|
POST |
|
Reactivate paused products on a specific line item, allowing them to be advertised again. |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Product ID, unique identifier at the Retailer catalog and obtained from the account Catalog
Accepted values: up to
Writeable? N / Nullable? N |
|
|
string |
Line Item ID, in which the product is to be promoted; required in the endpoints' path to define in which line item to perform the action Accepted values: string or int64 Writeable? N / Nullable? N |
|
|
decimal |
Bid value for the specific product; overrides
Accepted values:
Writeable? N / Nullable? Y |
|
|
enum |
Status of Promoted Product; can only be updated to
For more details about each state, check out Campaign, Line Item & Products Status
Returned values:
Writeable? Y / Nullable? N |
|
Response |
Description |
|---|---|
|
🟢
|
Call completed with success |
|
🟢
|
Promoted product paused or unpaused with success (no body content returned) |
|
🔴
|
Bad Request - Common validation errors:
|
|
🔴
|
API user does not have authorization to make requests for the account ID. For authorization, follow the authorization request steps. |
|
🔴
|
Line item ID not found |
## What's next * [Recommended Keywords](/retail-media/docs/recommended-keywords) * [Recommended Categories](/retail-media/docs/recommended-categories) * [Category Search](/retail-media/docs/category-search) # Real-Time Performance Report Source: https://developers.criteo.com/retail-media/docs/real-time-performance-api Retrieve near real-time campaign performance data synchronously using the Retail Media Real-Time Performance API ## Introduction The Retail Media Real-Time Performance API is a synchronous reporting endpoint that exposes **near real-time campaign performance data from the Retail Media reporting platform**. This API is designed for: * Demand Side users accessing through a Commerce Yield Private Market account, * Demand Side users accessing through a Commerce Max Network account. Typical use-cases for this endpoint include, for example: * Real-time monitoring during major retail events (for example, Black Friday, Prime Day, etc.), * Live optimization dashboards for trading teams, * Alerting systems reacting to sudden performance changes (spend drops/spikes, click anomalies, etc.).
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Retrieves real-time Retail Media performance metrics |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
date |
Start date (YYYY-MM-DD) for the reporting window. Must be no more than 7 days in the past in the requested timezone. |
|
|
date |
End date (YYYY-MM-DD) for the reporting window. Optional |
|
|
array of strings |
Single retailer ID filter. Optional |
|
|
array of strings |
Filter by account IDs. Max 5 IDs.
Choose
one
of:
|
|
|
array of strings |
Filter by campaign IDs. Max 50 IDs.
Choose
one
of:
|
|
|
array of strings |
Filter by line item IDs. Max 50 IDs.
Choose
one
of:
|
|
|
array of strings |
Grouping dimensions. Must contain at least one value. |
|
|
array of strings |
Requested metrics. Must contain at least one value. |
|
|
string |
Time zone identifier. Defaults to UTC if not provided. |
|
Response |
Title |
Detail |
Troubleshooting |
|---|---|---|---|
|
🟢
|
Success |
Data returned successfully |
Call executed with success |
|
🔴
|
Validation Error |
Invalid request (timezone, filters, dimensions, metrics, look back, etc.) |
Review request parameters |
|
🔴
|
Missing Entity Filters |
No
|
Provide exactly one entity filter |
|
🔴
|
Entity Filter Limit Exceeded |
Too many IDs provided |
Respect max limits |
|
🔴
|
Missing Metrics |
metrics is missing or empty |
Provide at least one metric |
|
🔴
|
Missing Dimensions |
dimensions is missing or empty |
Provide at least one dimension |
|
🔴
|
Look back Window Exceeded |
|
Ensure ≤ 7 days |
|
🔴
|
Invalid Timezone |
Unsupported timezone |
Use valid timezone |
|
🔴
|
Deserialization Error |
Invalid format or type |
Fix payload format |
|
🔴
|
Forbidden |
Unauthorized access to resources |
Check permissions |
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Gets the top 50 recommended categories for specified products |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Unique identifier for the retailer. Found using the
Required in URL path. Writable? N / Nullable? N |
|
|
|
Array of product ID strings for category recommendations. Min: 1 item, Max: 1000 items. Required field. Writable? Y / Nullable? N |
|
Code |
Meaning |
Troubleshooting Hint |
|---|---|---|
|
🟢 200 |
Success |
Request processed successfully, returns up to 50 recommended categories. |
|
🔴 400 |
Bad Request |
Check that
|
|
🔴 403 |
Forbidden |
Verify authorization and retailer access permissions. |
## What's next * [Recommended Keywords](/retail-media/docs/recommended-keywords) * [Category Search](/retail-media/docs/categories) # Recommended Keywords Source: https://developers.criteo.com/retail-media/docs/recommended-keywords ## Introduction The Recommended Keywords endpoint helps to discover the most relevant keywords for your advertising campaigns by leveraging Criteo's advanced Keyword Service technology. This is the same algorithm used to generate keywords for Sponsored Products line items that serve on search pages across retail environments. When you provide `product IDs`, this endpoint analyzes your products and returns the top 100 keywords that your Sponsored Product and Onsite Display line items would serve on when shoppers search for related terms. This data-driven approach ensures your campaigns target the most effective keywords based on actual search behavior and product relevance. The Recommended Keywords are particularly valuable for **campaign optimization**, **keyword expansion strategies**, and **understanding how your products align with shopper search intent**. By using these recommendations, you can improve campaign performance and reach more qualified shoppers who are actively searching for products like yours. *** ## Endpoints
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Gets the top 100 recommended keywords for specified products |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Unique identifier for the retailer. Found using the
Required in URL path. Writable? N / Nullable? N |
|
|
|
Array of product ID strings for keyword recommendations. Min: 1 item, Max: 1000 items. Required field. Writable? Y / Nullable? N |
|
Code |
Meaning |
Troubleshooting Hint |
|---|---|---|
|
🟢 200 |
Success |
Request processed successfully, returns up to 100 recommended keywords |
|
🔴 400 |
Bad Request |
Check if
|
|
🔴 403 |
Forbidden |
Verify authorization and retailer access permissions |
## What's next * [Category Search](/retail-media/docs/category-search) # Retailer Budgets Source: https://developers.criteo.com/retail-media/docs/retailer-budgets ## Introduction
|
Verb |
Endpoint |
Description |
|---|---|---|
|
GET |
|
Get a single balance. Now includes
|
|
GET |
|
List balances. Now includes retailer fields. Retailer-budgets balances hidden on prior versions. |
|
GET |
|
Get balance change history. Now includes
|
|
POST |
|
Add campaigns to a balance. Validates retailer consistency. |
|
POST |
|
Remove campaigns from a balance. Returns error for retailer-billed balances. |
|
POST |
|
Create a campaign. Now accepts and validates
|
|
GET |
|
List campaigns. Now returns
|
|
GET |
|
Get a campaign. Now returns
|
|
POST |
|
Create a line item. Enforces
|
|
POST |
|
Search retailers. Now returns
|
|
Attribute |
Data Type |
Mutable |
Description |
|---|---|---|---|
|
|
|
init |
Retailer this balance is scoped to. Present only on retailer-budgets balances. *Nullable?* Y (null for non-retailer-billed) |
|
|
|
always |
Retailer purchase order number.
Replaces
the removed
*Nullable?* Y |
|
|
|
always |
Criteo purchase order number.
Replaces
the removed
*Nullable?* Y |
|
|
|
init |
Billing type for Private Market. Values:
|
|
\~\~
|
~~string~~ |
— |
Removed
in
|
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
The retailer this campaign is associated with. Required when using a retailer-budgets balance. Writeable? Y (at create) Nullable? Y (for non-retailer-budgets campaigns) |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Budget model(s) supported for the given
Values:
Writeable? N Nullable? N |
|
Error code |
Endpoint |
Meaning |
|---|---|---|
|
|
|
Cannot remove a retailer-budgets balance from a campaign. |
|
|
|
Campaign
|
|
|
|
Line item
|
|
Response |
Title |
Detail |
Troubleshooting |
|---|---|---|---|
|
🟢
|
Success |
Request executed successfully. |
|
|
🔴
|
Retailer-budget balance mapping |
"Only retailer-sold campaigns are allowed to be mapped to a retailer-billed balance." |
Only campaigns scoped to the same retailer as the balance can be appended via
|
|
🔴
|
|
Campaign
|
Ensure the
|
|
🔴
|
|
Line item
|
Ensure
|
|
🔴
|
|
A required field is missing or has an invalid value. |
Review the request body against the attributes table above. |
|
🔴
|
|
Verify your access token and that your account has access to the retailer in question. |
|
Method |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Search for Retailers associated with specific account |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Retailer ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
|
Retailer name, arbitrary and defined during Retailer integration phase Accepted values: up to 100-chars string Writeable? Y / Nullable? N |
|
|
|
Set of retail media capabilities available for the specific Retailer, separated by the different
Accepted values: see table below Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Campaign type that the following attributes are available for
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Buy type for the ad impressions of the campaign, that the following attributes are available for
Accepted values:
Writeable? N / Nullable? N |
|
|
|
Budget models available for this
Values:
Writeable? N / Nullable? Y |
|
|
|
List of page type and environment where the campaign type & buy type are available to deliver ad impressions
Accepted values: list of
Writeable? N / Nullable? N |
|
|
|
Page type available in the current integration of the associated Retailer Accepted values: case-insensitive values of
Writeable? N / Nullable? N |
|
|
|
Environment where the page type is available in the associated Retailer integration Accepted values: case-insensitive values of
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Optional list of Retailer IDs, generated internally by Criteo, to retrieve retail media capabilities from
Accepted values: list of integers, empty list or
|
|
Response |
Description |
|---|---|
|
🟢
|
Call executed with success |
|
🔴
|
"*Model validation error: The field limit must be between 1 and 10*". This indicates that the endpoint above was invoked requesting more than 10 retailers, which is not possible. Define a
|
|
🔴
|
API user does not have the authorization to make requests to the account ID. For an authorization request, follow the authorization request steps |
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Request a retailer revenue report creation |
|
GET |
|
Get status of a specific report |
|
GET |
|
Download output of a specific report |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
|
Supply Account ID to pull results for
Note: for apps with access to multiple supply accounts, it is also possible to use an
Accepted values:
Writable? N / Nullable? N |
|
|
|
Report types are pre-packaged reports that allow the specification of the report breakdown. They enable reports to view revenue distribution by advertiser, brand, environment, page category, and page type. The metrics and dimensions in these report types are limited.
Use the
*Note: when metrics and dimensions are used, the report type is ignored.*
Accepted values:
Writable? N / Nullable? Y |
|
|
|
The revenue type used to filter report results. If the revenue type filter is not specified, the report will return all existing revenue data for sponsored products and preferred deals within the specified timeframe.
Accepted values:
Writable? N / Nullable? Y |
|
|
|
The sales channel of indirect sold, direct sold, or private market. This is an optional filter that can be used to narrow down results.
Accepted values:
Writable? N / Nullable? Y |
|
|
|
Filter on the budget model. Optional.
Accepted values:
Writable? N / Nullable? Y |
|
|
|
Filter on the activation platform. Optional.
Accepted values:
Writable? N / Nullable? Y |
|
|
|
The campaign buying strategy. This optional filter can be used to filter down results
Accepted values:
Writable? N / Nullable? Y |
|
|
|
The format type the report should return results
Accepted values:
Writable? N / Nullable? N |
|
|
|
The campaign type to filter results
Accepted values:
Default:
Writable? N / Nullable? N |
|
|
|
The sales channel where attributed sales originated
Accepted values:
Default:
Writable? N / Nullable? N |
|
|
|
The advertiser type where campaigns originated from
Accepted values:
Writable? N / Nullable? N |
|
|
|
The post-click attribution window, defined as the maximum number of days considered between a click and a conversion for attribution; conversions are attributed to the date of conversion, not the date of click.
Accepted values:
Default: if omitted, defaults to
Campaign
settings; must be specified if
Writable? N / Nullable? Y |
|
|
|
The post-view attribution window, defined as the maximum number of days considered between an impression and a conversion for attribution; conversions are attributed to the date of conversion, not the date of impression.
Accepted values:
Default: if omitted, defaults to
Campaign
settings; must be less than or equal to
Writable? N / Nullable? Y |
|
|
|
An array of strings used to define which dimensions to see in the report Accepted values: refer to Metrics and Dimensions for the complete list of supported dimensions Writable? N / Nullable? Y |
|
|
|
The attribution configuration modal allows users to retrieve data based on the specified product match for click events.
The order of product match relationships from farthest to closest is
*This is not a filter that excludes events. Rather, it calculates attribution using the provided SKU match level.*
Accepted values:
Default: if omitted, defaults to Campaign settings Writable? N / Nullable? Y |
|
|
|
The attribution configuration modal allows users to retrieve data based on the specified product match for view events.
The order of product match relationships from farthest to closest is
*This is not a filter that excludes events. Rather, it calculates attribution using the provided SKU match level.*
Accepted values:
Default: if omitted, defaults to Campaign settings Writable? N / Nullable? Y |
|
(DEPRECATED) |
|
The attributed rule used to match an impression/click to a sale. The filter will narrow down results of the attributed rules set by the advertiser at the campaign level.
Accepted Values:
Writable? N / Nullable? Y
⚠️
Note
: This filter is
deprecated
. Please use
|
|
|
|
An array of strings used to define which metrics to see in the report. Accepted values: refer to Metrics and Dimensions for the complete list of supported metrics Writable? N / Nullable? Y |
|
|
|
Start date of the report (inclusive)
Accepted values:
Writable? N / Nullable? N |
|
|
|
End date of the report (inclusive)
Accepted values:
Writable? N / Nullable? N |
|
|
|
Time zone to consider in the metrics calculation,
Accepted values:
IANA (TZ database)
time zones (example:
Default:
Writable? N / Nullable? Y |
|
|
|
Gives the ability for the user to filter by account IDs. *There are currently no limitations to the amount of IDs that can be added to the filter.* |
|
|
|
Gives the ability for the user to filter by campaign IDs. *There are currently no limitations to the amount of IDs that can be added to the filter.* |
|
|
|
Gives the ability for the user to filter by line item IDs. *There are currently no limitations to the amount of IDs that can be added to the filter.* |
|
|
|
Gives the ability for the user to filter their reporting by retailer ID(s). |
|
Response |
Description |
|---|---|
|
🔵
|
Call executed with success |
|
🔴
|
Common Validation Errors:
|
## What's next * [Metrics and Dimensions (SSP)](/retail-media/docs/metrics-and-dimensions-ssp) # Sellers Source: https://developers.criteo.com/retail-media/docs/sellers ## Introduction A seller represents an external entity that sells products in the retailers' environment (marketplace). Sellers entities are, initially, available through retailers' catalogs and can aggregate different products offered by them in the retailer marketplace. A demand account can be associated with multiple sellers (across multiple retailers) and be willing to serve ads across them. This endpoint provides a programmatic way to identify all sellers (and, consequently, retailers) associated with the respective account, so that campaigns can be set up accordingly. *** ## Endpoints
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Search for Sellers, associated with retailers, given an account ID |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Account ID, to consider in the search for Seller accounts Accepted values: int64 Writeable? N / Nullable? N |
|
|
boolean |
Flag indicating to include accounts' details in the response, such as
It may improve performance when set to
Accepted values:
Default:
Writeable? N / Nullable? Y |
|
|
string |
Seller ID, specific to the associated Retailer Accepted values: int64 Writeable? N / Nullable? N |
|
|
integer |
Retailer ID which the seller account is associated with Accepted values: int32 Writeable? N / Nullable? N |
|
|
string |
Seller name Accepted values: string Writeable? N / Nullable? Y |
|
Response |
Error |
Message |
Description |
|---|---|---|---|
|
🟢
|
Call completed successfully |
||
|
🔴
|
Validation Error |
|
One of the parameters provided in the request does not match the format accepted. Check the error details and the parameters informed in the call |
|
🔴
|
Authorization Error |
|
API user does not have the authorization to make requests to the account ID. For an authorization request, follow the authorization request steps |
## What's next * [Retailers](/retail-media/v2025.07/docs/retailers) # Store Inventory Source: https://developers.criteo.com/retail-media/docs/store-inventory Manage product availability and pricing at the store level using the Store Inventory API ## Introduction **Store Inventory** enables retailers to manage product availability and pricing at the store level, supporting accurate PDP/ad experiences. Inventory events (upserts and deletes) are sent in batches, enabling real-time updates for price and availability per store. This API is **event-driven** and **multi-tenant**.
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Insert or update store(s) |
|
POST |
|
Delete store(s) |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
integer |
The ID of the managing account.
Criteo: the
Accepted values: integer (int32) Writeable? N / Nullable? N |
|
|
string |
Identifies this event. Should be unique for a given endpoint call. Writeable? Y / Nullable? N |
|
|
string |
Identifies a product Accepted values: up to 50 chars string Writeable? Y / Nullable? N |
|
|
string |
Identifies the store for the customer. Accepted values: up to 64 chars string Writeable? Y / Nullable? N |
|
|
string |
Accepted values:
Writeable? Y / Nullable? N |
|
|
string |
Product's price at this store Accepted values: up to 14 chars string Writeable? Y / Nullable? N |
|
|
string |
The sale price of the product Accepted values: up to 14 chars string Writeable? Y / Nullable? Y |
|
Error code |
Error text |
Description |
|---|---|---|
|
400 |
Bad request |
Validation errors, required fields, unique
|
|
400 |
Request too large |
Payload exceeds 1000 events |
|
401 |
Unauthorized |
Authentication required |
|
403 |
Forbidden |
Not authorized |
|
429 |
Too Many Requests |
Rate limiting |
|
500 |
Internal Error |
Server error |
|
503 |
Service Unavailable |
Service temporarily unavailable |
## What's next * [Revenue Report](/retail-media/docs/revenue-report-ssp) * [Metrics and Dimensions (SSP)](/retail-media/docs/metrics-and-dimensions-ssp) * [Fill Rate Report](/retail-media/docs/fill-rate-report) * [Reporting Diagnostic Guide](/retail-media/docs/reporting-overview-diagnostic-guide) # Welcome to Criteo Retail Media API Source: https://developers.criteo.com/retail-media/docs/welcome-to-criteo
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/fillrate Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportsfillrate https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/fillrate Returns an asynchronous Fill Rate Report
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/missed-opportunities Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportsmissed-opportunities https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/missed-opportunities Creates a missed-opportunities async report. The request accepts explicit missed-opportunities dimensions, metrics, and filters.
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/performance Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportsperformance https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/performance Creates a performance DSP analytics async report. Dimensions and metrics select the output schema, and filters constrain eligible data.
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/revenue Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportsrevenue https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/revenue Returns an asynchronous Revenue Report
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/sync/attributed-transactions Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportssyncattributed-transactions https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/sync/attributed-transactions Returns a synchronous Attributed Transactions Report # /2026-07/retail-media/reports/sync/campaigns Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportssynccampaigns https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/sync/campaigns Returns a synchronous Campaigns Report # /2026-07/retail-media/reports/sync/line-items Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportssyncline-items https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/sync/line-items Returns a synchronous Line Items Report # /2026-07/retail-media/reports/sync/real-time-performance Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportssyncreal-time-performance https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/sync/real-time-performance Returns a synchronous Real Time Performance Report. Returns empty rows; metadata includes dataCompleteThrough (latest time from streaming table in the request timezone).
This endpoint is subject to specific rate limits. # /2026-07/retail-media/reports/unfilled-placements Source: https://developers.criteo.com/retail-media/v2026.07/reference/analytics/2026-07retail-mediareportsunfilled-placements https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/reports/unfilled-placements Returns an asynchronous Unfilled Placements Report
This endpoint is subject to specific rate limits. # /2026-07/retail-media/billing/partner-report Source: https://developers.criteo.com/retail-media/v2026.07/reference/billing/2026-07retail-mediabillingpartner-report https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/billing/partner-report Create a Partner Billing Report request. # /2026-07/retail-media/billing/partner-report/{requestId}/output Source: https://developers.criteo.com/retail-media/v2026.07/reference/billing/2026-07retail-mediabillingpartner-report-output https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/billing/partner-report/{requestId}/output Get the output of an existing Partner Billing Report. # /2026-07/retail-media/billing/partner-report/{requestId}/status Source: https://developers.criteo.com/retail-media/v2026.07/reference/billing/2026-07retail-mediabillingpartner-report-status https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/billing/partner-report/{requestId}/status Get the status of an existing Partner Billing Report. # /2026-07/retail-media/line-items/{lineItemId}/line-item-budget-overrides Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-line-item-budget-overrides https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/line-items/{lineItemId}/line-item-budget-overrides Gets a collection of monthly and daily budget overrides for the provided line item. # /2026-07/retail-media/line-items/{lineItemId}/line-item-budget-overrides Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-line-item-budget-overrides-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json put /2026-07/retail-media/line-items/{lineItemId}/line-item-budget-overrides Update line item budget overrides by given external line item id and new line item budget overrides settings. # /2026-07/retail-media/line-items/{line-item-id}/products/append Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-productsappend https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/line-items/{line-item-id}/products/append Append a collection of promoted products to a line item # /2026-07/retail-media/line-items/{line-item-id}/products/delete Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-productsdelete https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/line-items/{line-item-id}/products/delete Remove a collection of promoted products from a line item # /2026-07/retail-media/line-items/{line-item-id}/products/pause Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-productspause https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/line-items/{line-item-id}/products/pause Pause a collection of promoted products associated with a line item # /2026-07/retail-media/line-items/{line-item-id}/products/unpause Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-medialine-items-productsunpause https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/line-items/{line-item-id}/products/unpause Un-pause a collection of promoted products associated with a line item # /2026-07/retail-media/preferred-line-items/{line-item-id} Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/preferred-line-items/{line-item-id} Gets the preferred line item for the given line item id # /2026-07/retail-media/preferred-line-items/{line-item-id} Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json put /2026-07/retail-media/preferred-line-items/{line-item-id} Updates the preferred line item for the given line item id # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingadd-to-basket https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket This endpoint gets the add to basket target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingadd-to-basket-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json put /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket This endpoint sets the scope of the add to basket target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/append Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingadd-to-basketappend https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/append This endpoint appends one or more add to basket ids to targeting on the specified line item. The resulting state of the add to basket target is returned. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/delete Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingadd-to-basketdelete https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/delete This endpoint removes one or more add to basket ids from targeting on the specified line item. The resulting state of the add to basket target is returned. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingaudiences https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences This endpoint gets the audience target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingaudiences-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json put /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences This endpoint sets the scope of the audience target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/append Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingaudiencesappend https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/append This endpoint appends one or more audiences ids to targeting on the specified line item. The resulting state of the audience target is returned. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/delete Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingaudiencesdelete https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/delete This endpoint removes one or more audiences ids from targeting on the specified line item. The resulting state of the audience target is returned. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingstores https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores This endpoint gets the store target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingstores-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json put /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores This endpoint sets the scope of the store target on the specified line item. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores/append Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingstoresappend https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores/append This endpoint appends one or more store ids to targeting on the specified line item. The resulting state of the store target is returned. # /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores/delete Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediapreferred-line-items-targetingstoresdelete https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/preferred-line-items/{line-item-id}/targeting/stores/delete This endpoint removes one or more store ids from targeting on the specified line item. The resulting state of the store target is returned. # /2026-07/retail-media/retailers/{retailerId}/categories/search Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-categoriessearch https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/retailers/{retailerId}/categories/search Search a retailer categories by given text substring and category ids. # /2026-07/retail-media/retailers/{retailerId}/cpc-min-bids Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-cpc-min-bids https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/retailers/{retailerId}/cpc-min-bids Get overall and individual minimum bid amount for given retailer id and sku id list. # /2026-07/retail-media/retailers/{retailerId}/pages Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-pages https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/retailers/{retailerId}/pages Get the page types available for the given retailer # /2026-07/retail-media/retailers/{retailerId}/recommend-categories Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-recommend-categories https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/retailers/{retailerId}/recommend-categories Endpoint to get recommended categories by given retailer id and sku id list. # /2026-07/retail-media/retailers/{retailerId}/recommend-keywords Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-recommend-keywords https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/retailers/{retailerId}/recommend-keywords Recommend keywords by given retailer id and sku ids. # /2026-07/retail-media/retailers/{retailer-id}/templates Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-templates https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/retailers/{retailer-id}/templates Get retailer creative templates # /2026-07/retail-media/retailers/{retailer-id}/templates/{template-id} Source: https://developers.criteo.com/retail-media/v2026.07/reference/campaign/2026-07retail-mediaretailers-templates-1 https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/retailers/{retailer-id}/templates/{template-id} Gets the template for the specified retailer id and template id # /2026-07/retail-media/catalog/merchants/{merchantId}/store-inventory/delete Source: https://developers.criteo.com/retail-media/v2026.07/reference/catalog/2026-07retail-mediacatalogmerchants-store-inventorydelete https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/catalog/merchants/{merchantId}/store-inventory/delete Used to publish a batch of store inventories to delete. The batch is processed asynchronously. # /2026-07/retail-media/catalog/merchants/{merchantId}/store-inventory/upsert Source: https://developers.criteo.com/retail-media/v2026.07/reference/catalog/2026-07retail-mediacatalogmerchants-store-inventoryupsert https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json post /2026-07/retail-media/catalog/merchants/{merchantId}/store-inventory/upsert Used to publish a batch of store inventories to upsert. The batch is processed asynchronously. # /2026-07/retail-media/me Source: https://developers.criteo.com/retail-media/v2026.07/reference/gateway/2026-07retail-mediame https://api.criteo.com/2026-07/retailmedia/open-api-specifications.json get /2026-07/retail-media/me Get information about the currently logged application # Ad Set Source: https://developers.criteo.com/marketing-solutions/docs/ad-set Criteo's **Campaign API** allows you to retrieve information about the current configuration of your advertising Ad Sets. This API allows you to **create** adSets, **search** for Ad Sets based on filters, **start and stop** Ad Sets, and **update** your Ad Sets' names, start and end dates, bid amounts, frequency capping, and other targeting controls. ## **Ad Set Example** The following is an example of the JSON data structure of an Ad Set. Additional details about the individual attributes of Ad Sets can be found below. ```json Example Ad Set expandable theme={null} { "data": { "type": "ReadAdSet", "id": "123467", "attributes": { "name": "Campaign A", "advertiserId": "12345", "objective": "conversions", "destinationEnvironment": "app", "mediaType": "Display", "datasetId": "6789", "campaignId": "1485", "schedule": { "startDate": "2018-07-04T00:00:00Z", "endDate": "2018-07-26T00:00:00Z", "activationStatus": "on", "deliveryStatus": "live" }, "bidding": { "bidAmount": 0.9, "costController": "MaxCPC", }, "targeting": { "frequencyCapping": { "frequency": "hourly", "maximumImpressions": 3 }, "geoLocation": { "countries": {"values": ["FR"], "operand": "in"}, "subdivisions": {"values": ["FR-01", "FR-38"], "operand": "notIn"}, "zipCodes": null }, "deliveryLimitations": { "devices": ["mobile", "tablet"], "operatingSystems": ["ios"], "environments": [] } }, "budget": { "budgetStrategy": "capped", "budgetRenewal": "daily", "budgetDeliverySmoothing": "accelerated", "budgetDeliveryWeek": "undefined", "budgetAmount": {"value": 123.45} }, "attributionConfiguration": { "attributionMethod": "criteoAttribution", "lookbackWindow": null } } }, "warnings": [], "errors": [] } ``` ## **Ad Set Attributes** **`name`**\ The Ad Set name, set by the advertiser. **`destinationEnvironment`**\ Read-only. The environment that an ad click will lead a user to. **`objective`**\ The intended optimization for the Ad Set. Can be `customAction`, `clicks`, `conversions`, `displays`, `appPromotion`, `revenue`, `storeConversions`, `value`, `reach`, `visits` or `videoViews` (only when mediaType is set to Video) **`mediaType`**\ The type of media the ad set will deliver on. Can be `Display` or `Video` **`datasetId`**\ Data Set Id associated with the specified advertiser ID. See [Datasets](/marketing-solutions/v2026-preview/docs/datasets) for how to find datasets associated to advertisers. **`campaignId`**\ Id of the marketing campaign associated to the ad set. See [Search for Campaigns](/marketing-solutions/docs/campaign#searching-campaigns) for how to search for campaigns. ### Ad Set Schedule **`schedule.startDate`**\ ISO 8601 format. It must always be earlier than the `schedule.endDate`. It's a mandatory parameter of the Schedule object. This condition applies only if an `endDate` is defined. **`schedule.endDate`**\ ISO 8601 format. `null` by default. (`null` is a valid value.) **`schedule.activationStatus`**\ Can be `on` or `off`. `off` by default. Set by the advertiser, this represents the intent to deliver ads. See [Start and Stop Ad Sets](/marketing-solutions/docs/ad-set#start-an-ad-set) for how to change this value. **`schedule.deliveryStatus`**\ Can be `draft`, `inactive`, `live`, `notLive`, `pausing`, `paused`, `scheduled`, `ended`, `notDelivering`, or `archived`. The initial value for a newly created Ad Set is `draft`. This is a **computed value** and is read-only.
## What's next * [Get Advertiser Portfolio](/marketing-solutions/docs/get-advertiser-portfolio) # Algebra Nodes Source: https://developers.criteo.com/marketing-solutions/docs/algebra-nodes ## Introduction
|
Field Name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
String |
Computed |
Unique ID of the audience |
|
|
String |
Required |
Name of the audience. It must be unique per advertiser. |
|
|
String |
Optional |
Description of the audience |
|
|
String |
Computed |
ISO-8601 timestamp in UTC of audience creation (read-only) |
|
|
String |
Computed |
ISO-8601 timestamp in UTC of audience update (read-only) |
|
|
String |
Required |
Advertiser associated to the audience |
|
|
String Array |
Computed |
Ad sets associated to the audience (read-only). |
|
|
Required |
Algebra Node with the definition of how the different segments are mixed to create the audience using logical operators: AND, OR, NOT. |
|
Name |
Required / Optional |
Description |
|---|---|---|
|
|
optional |
The number of elements to be returned. The default is 50 and the maximum is 100. |
|
|
optional |
The (zero-based) offset into the collection. The default is 0. |
|
Field name and type |
Type |
Possible value |
Optional / Required / Computed |
Description |
|---|---|---|---|---|
|
|
String |
Required |
Unique ID of the segment |
|
|
|
String |
Required |
Name of the segment. It must be unique per advertiser. |
|
|
|
String |
Optional |
Description of the segment |
|
|
|
|
|
Computed |
Type of audience segment (read-only). Once created, the type cannot be changed. |
|
|
String |
Computed |
ISO-8601 timestamp in UTC of segment creation (read-only) |
|
|
|
Computed |
ISO-8601 timestamp in UTC of segment update (read-only) |
||
|
|
String |
Required |
Advertiser associated to the segment |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
In-market |
Optional |
Indicates that this should be an Audience Segment of type In-market |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
country |
String The ISO 3166-1 alpha-2 country code |
Required (if In-market is set) |
Reach people of a specific country. |
|
buyingPower |
BuyingPower array BuyingPower can be:
|
Optional |
Reach people who frequently purchase high price range items to lower price range items. If empty, don't filter people based on buying power. |
|
gender |
Gender Gender can be:
|
Optional |
Reach people who’ve shown interest in products made for a specific gender. If empty, don't filter people based on gender. |
|
String array |
Required (if In-market is set) |
Reach new people based on their commercial interests |
|
|
String array |
Required (if In-market is set) |
Choose the commercial brands your segment might be interested in |
|
|
priceRange |
PriceRange array PriceRange can be:
|
Optional |
Reach people who’ve shown interest in products within a specific price range. If empty, don't filter people based on price range. |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
ContactList |
Optional |
Indicates that this should be an Audience Segment of type Contact List |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
isReadOnly |
Boolean |
Computed |
True if the contact list-specific information cannot be edited through the public API, false otherwise. Contact Lists can be created through the Public API or through Commerce Growth, and this determines where they’re editable: if created through the Public API, they can only be edited through the Public API; same for Commerce Growth.
Segments created in Commerce Growth will show up as
|
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
Location |
Optional |
Indicates that this should be an Audience Segment of type Location |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
registryType |
RegistryType RegistryType can take only one value (for now):
|
Required (if location set) |
The type of location audience segment |
|
pointsOfInterest |
PointsOfInterest array. Each point has a name, latitude and longitude |
Required (if location set) |
Reach users which have been historically located in the given coordinates |
|
→ name |
String |
Required |
Name of the point of interest |
|
→ latitude |
Decimal |
Required |
ISO-6709 latitude |
|
→ longitude |
Decimal |
Required |
ISO-6709 longitude |
|
radiusInKm |
Integer |
Required (if location set) |
The expected maximum distance in kilometers between a user and a point of interest |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
Behavioral |
Computed |
Indicates that this should be an Audience Segment of type Behavioral |
|
Field name |
Type |
Optional / Required / Computed |
Default Value |
Description |
|---|---|---|---|---|
|
country |
String |
Computed |
The user's country |
|
|
category |
BehavioralCategory. Can take any of these values:
|
Computed |
The behavioral's category |
|
|
startDate |
DateTime |
Computed (can be empty) |
Empty |
The date when this audience segment will start to be filled with audience data |
|
endDate |
DateTime |
Computed (can be empty) |
Empty |
The date when this audience segment will be cleaned of audience data |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
Prospecting |
Optional |
Indicates that this should be an Audience Segment of type Prospecting |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
Lookalike |
Optional |
Indicates that this should be an Audience Segment of type Lookalike |
|
Field |
Type |
Mandatory |
Description |
|---|---|---|---|
|
|
string |
Yes |
Id of existing Contact List or Event segment that will be treated as a seed. |
|
|
int64 |
No |
The target size of the resulting segment after computation. |
|
Field name |
Type |
Optional / Required / Computed |
Description |
|---|---|---|---|
|
|
Retargeting |
Optional |
Indicates that this should be an Audience Segment of type Retargeting |
|
Name |
Type |
Optional/Required |
Description |
|---|---|---|---|
|
visitorsType |
VisitorsType Can take three values:
*
*
|
Required |
The type of users being targeted. |
|
daysSinceLastVisitMin |
Integer |
Required |
Include users who visited your website before this number of days |
|
daysSinceLastVisitMax |
Integer |
Required |
Include users who visited your website after this number of days |
|
Name |
Required / Optional |
Description |
|---|---|---|
|
|
required |
The Advertiser Id |
|
|
required |
The ISO 3166-1 alpha-2 country code |
|
Name |
Required / Optional |
Description |
|---|---|---|
|
|
required |
The Advertiser Id |
|
|
required |
The ISO 3166-1 alpha-2 country code |
# Authentication Source: https://developers.criteo.com/marketing-solutions/docs/authentication ## Introduction To get started with our APIs, you will need to use the endpoint below to generate an Access Token, with your API credentials or authorization code. The Access Token is a Bearer token that needs to be included in the Authorization Header of all API requests. Multiple tokens may be generated and each is valid for 15 minutes, or 900 seconds *** ## Endpoint ### Generate an Access Token ```http theme={null} POST https://api.criteo.com/oauth2/token ```
|
Parameter |
Type |
Description |
|---|---|---|
|
|
string |
Please see below for instructions on getting your credentials through Partner Dashboard |
|
|
string |
Please see below for instructions on getting your credentials through Partner Dashboard |
|
|
string |
Must be
|
|
|
string |
Only for Authorization Code apps . Authorization code returned during redirection |
|
|
string |
Only for Authorization Code apps
. Must match the
|
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
A list of advertiser ids (comma separated) |
string |
N |
|
|
The currency to be used in the report, ISO format. A list of supported currencies is available here. |
string |
Y |
|
|
Start date, ISO 8601 format. |
string |
Y |
|
|
End date, ISO 8601 format. |
string |
Y |
|
|
The output format. CSV, JSON, XML or EXCEL. |
string |
Y |
|
|
See the Dimensions page. |
Arrayk:api-he |
Y |
|
|
See the Metrics page. |
Arrayk:api-he |
Y |
|
|
The timezone for organizing the data in the report. A list of supported values is available here. |
string |
N UTC will be default timezone if not specified. |
|
Type |
Dimension |
|---|---|
|
Campaign |
|
|
Time |
|
|
Other |
|
|
Currency Code |
Symbol |
Full Name |
|---|---|---|
|
EUR |
€ |
Euro |
|
USD |
\$ |
US Dollar |
|
GBP |
£ |
British Pound |
|
CHF |
Ch |
Swiss Franc |
|
JPY |
¥ |
Japanese Yen |
|
BGN |
Л |
Bulgarian Lev |
|
CZK |
K |
Czech Koruna |
|
DKK |
Kr |
Danish Krone |
|
HUF |
Ft |
Hungarian Forint |
|
LTL |
Lt |
Lithuanian Litas |
|
PLN |
Z |
Polish Zloty |
|
RON |
Le |
Romanian New Leu |
|
SEK |
Kr |
Swedish Krona |
|
NOK |
Kr |
Norwegian Krone |
|
HRK |
Kn |
Croatian Kuna |
|
RUB |
Р |
Russian Ruble |
|
TRY |
Tl |
Turkish Lira |
|
AUD |
\$ |
Australian Dollar |
|
BRL |
R\$ |
Brazilian Real |
|
CAD |
\$ |
Canadian Dollar |
|
CNY |
¥ |
Chinese Yuan Renminbi |
|
HKD |
Hk |
Hong Kong Dollar |
|
IDR |
Rp |
Indonesian Rupiah |
|
INR |
Rs |
Indian Rupee |
|
KRW |
N/A |
South Korean Won |
|
MXN |
\$ |
Mexican Peso |
|
MYR |
Rm |
Malaysian Ringgit |
|
NZD |
\$ |
New Zealand Dollar |
|
PHP |
N/A |
Philippine Peso |
|
SGD |
\$ |
Singapore Dollar |
|
THB |
N/A |
Thai Baht |
|
ZAR |
R |
South African Rand |
|
ARS |
\$ |
Argentine Peso |
|
COP |
\$ |
Colombian Peso |
|
AED |
د |
United Arab Emirates Dirham |
|
KZT |
Т |
Kazakhstani Tenge |
|
SAR |
N/A |
Saudi Riyal |
|
UAH |
N/A |
Ukrainian Hryvnia |
|
EGP |
£ |
Egyptian Pound |
|
MAD |
Dh |
Moroccan Dirham |
|
ILS |
N/A |
Israeli Shekel |
|
BHD |
Bd |
Bahraini Dinar |
|
JOD |
Jd |
Jordanian Dinar |
|
KWD |
ك |
Kuwaiti Dinar |
|
LBP |
ل |
Lebanese Pound |
|
OMR |
N/A |
Omani Rial |
|
QAR |
N/A |
Qatari Riyal |
|
NGN |
N/A |
Nigerian Naira |
|
KES |
Ks |
Kenyan Shilling |
|
ALL |
Le |
Albania Lek |
|
ETB |
Br |
Ethopian Birr |
|
BSD |
\$ |
Bahamian Dollar |
|
BDT |
N/A |
Bangladeshi Taka |
|
BAM |
Km |
Bosnia-Herzegovina Convertible Mark |
|
BWP |
P |
Botswana Pula |
|
MMK |
K |
Burmese Kyat |
|
AFN |
؋ |
Afghan Afghani |
|
BTN |
Nu |
Bhutanese Ngultrum |
|
GEL |
N/A |
Georgian Lari |
|
GHS |
Gh |
Ghanaian Cedi |
|
GIP |
£ |
Gibraltar Pound |
|
ISK |
Kr |
Icelandic Krona |
|
KHR |
N/A |
Cambodian Riel |
|
JMD |
J\$ |
Jamaican Dollar |
|
LAK |
N/A |
Lao Kip |
|
MKD |
Д |
Macedonian Denar |
|
MUR |
N/A |
Mauritian Rupee |
|
MNT |
N/A |
Mongolian Tögrög |
|
NPR |
N/A |
Nepalese Rupee |
|
NAD |
\$ |
Namibian Dollar |
|
PKR |
N/A |
Pakistani Rupee |
|
RWF |
Fr |
Rwandan Franc |
|
LKR |
N/A |
Sri Lankan Rupee |
|
SZL |
L |
Swazi Lilangeni |
|
TZS |
Ts |
Tanzanian Shilling |
|
TTD |
Tt |
Trinidad And Tobago Dollar |
|
UGX |
Us |
Ugandan Shilling |
|
ZMW |
Zk |
Zambian Kwacha |
|
BOB |
\$B |
Bolivian Boliviano |
|
CRC |
N/A |
Costa Rican Colón |
|
DOP |
Rd |
Dominican Peso |
|
GTQ |
Q |
Guatemalan Quetzal |
|
HNL |
L |
Honduran Lempira |
|
NIO |
C\$ |
Nicaraguan Córdoba |
|
PAB |
B/ |
Panamanian Balboa |
|
PYG |
Gs |
Paraguayan Guaraní |
|
PEN |
S/ |
Peruvian Nuevo Sol |
|
UYU |
\$U |
Uruguayan Peso |
|
VEF |
Bs |
Venezuelan Bolívar |
|
XAF |
Fr |
Central African Cfa Franc |
|
XOF |
Fr |
West African Cfa Franc |
|
HTG |
G |
Haitian Gourde |
|
MGA |
Ar |
Malagasy Ariary |
|
DZD |
د |
Algerian Dinar |
|
IQD |
د |
Iraqi Dinar |
|
LYD |
ل |
Libyan Dinar |
|
TND |
د |
Tunisian Dinar |
|
YER |
N/A |
Yemeni Rial |
|
BND |
\$ |
Brunei Dollar |
|
AOA |
Kz |
Angolan Kwanza |
|
MZN |
Mt |
Mozambican Metical |
|
AMD |
Am |
Armenian Dram |
|
AZN |
М |
Azerbaijani Manat |
|
KGS |
Л |
Kyrgyzstani Som |
|
TJS |
Tj |
Tajikistani Somoni |
|
UZS |
Л |
Uzbekistani Som |
|
MDL |
L |
Moldovan Leu |
|
RSD |
Д |
Serbian Dinar |
|
XPF |
Fr |
Cfp Franc |
|
MOP |
Mo |
Macanese Pataca |
|
VND |
N/A |
Viet Nam Dong |
|
TWD |
Nt |
Taiwan Dollar |
|
CLP |
\$ |
Chilean Peso |
|
Entity |
Description |
|---|---|
|
Advertiser |
Marketplace business entity |
|
Campaign (
|
Shared campaign configuration |
|
Seller (
|
Marketplace merchant |
|
Seller-Campaign (
|
Seller participation in a campaign |
|
Budgets |
Campaign-level and seller-level spend controls |
|
Type |
Description |
|---|---|
|
Campaign-level |
Shared across all sellers |
|
Seller-level |
Optional per seller-campaign |
|
Component |
Role |
|---|---|
|
Campaign Budget |
Total available spend |
|
CPC Bids |
Seller competitiveness |
|
Seller Budgets |
Optional caps per seller |
|
Issue |
Check |
|---|---|
|
No delivery |
Seller exists, CPC > 0, budgets active |
|
Low delivery |
CPC too low, budget limited |
|
Under-spend |
Campaign budget too small |
|
Over-spend |
Budget configuration / reset behaviour |
## What's next * [Commerce Grid Audience Segments Endpoints](/marketing-solutions/docs/commerce-grid-audience-segments-endpoints) # Commerce Grid Audience Segments Endpoints Source: https://developers.criteo.com/marketing-solutions/docs/commerce-grid-audience-segments-endpoints ## **Introduction** **Audience Segments** represent a groups of users to target.
|
Verb |
Endpoint |
Description |
|---|---|---|
|
POST |
|
Create a new Audience Segment |
|
PATCH |
|
Update an Audience Segment |
|
POST |
|
Delete an Audience Segment |
|
POST |
|
Search for Audience Segments by segment IDs, data provider IDs and/or segment types |
|
GET |
|
Retrieve contact list statistics |
|
POST |
|
Add/remove identifiers in contact list Audience Segment |
|
POST |
|
Clear all identifiers in contact list Audience Segment |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
Audience Segment ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
string |
Audience Segment name Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Description of the Audience Segment Accepted values: string Writeable? Y / Nullable? N |
|
|
string |
Data Provider ID associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
|
|
enum |
Type of segment Read-only value, which can be one of:
Writeable? N / Nullable? N |
|
|
object |
Setting to target users with contact list. See below for more details |
|
|
timestamp |
Timestamp of Audience Segment creation, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
|
timestamp |
Timestamp of last Audience Segment update, in UTC
Accepted values:
Writeable? N / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
string |
ID owned by the client and used to identify the Audience Segment. If none is provided, one will be generated internally by Criteo Accepted values: string Writeable? Y / Nullable? N |
|
Attribute |
Data Type |
Description |
|---|---|---|
|
|
enum |
Operation required for the sub-set of users provided in the request
Accepted values:
Writeable? Y / Nullable? N |
|
|
enum |
Type of identifiers that are being uploaded
Accepted values:
Writeable? Y / Nullable? N |
|
|
string\[] |
Array of identifiers represented as strings |
The API is currently in **beta** and is only available to a limited list of clients onboarded by the Criteo technical team. You can find the reference for the endpoints mentioned in the page in [the **Preview** version](/marketing-solutions/v2026-preview/reference/analytics/get-realtime-product) of this documentation.
Do not poll more than once every 5–10 seconds to remain within rate limits. * **Status options:** `Pending`, `Done`, `Failure`, `Expired`. * **Note:** Identical requests may reuse cached results, returning a previously generated ID. *** ## Step 3. Download Report Output
|
Endpoint |
Use case |
|---|---|
|
|
Template-level aggregation across all sellers |
|
|
Per-seller aggregation across campaigns |
|
|
Per seller-campaign (most granular) |
|
Identifier |
When to use |
|---|---|
|
|
Filter stats for all sellers under a specific template |
|
|
Filter stats for a specific seller across templates |
|
|
Filter stats for a specific seller on a specific template (most precise) |
|
Column in CSV |
Metric |
Type |
Description |
|---|---|---|---|
|
A |
Day |
String |
Day of impression or click event |
|
B |
Hour |
Integer |
Hour of impression or click event |
|
C |
Timestamp |
Integer |
Timestamp of impression or click event |
|
D |
Event type |
String |
Impression or click event specification |
|
E |
Campaign ID |
Integer |
Criteo-assigned numerical AdSet identifier |
|
F |
Campaign name |
String |
Name of AdSet as seen in Commerce Growth |
|
G |
Ad format |
String |
Format of display (i.e. 'mozaic' is a dynamic banner) |
|
H |
Banner ID |
Integer |
Criteo-assigned numerical banner identifier |
|
I |
Category ID |
Integer |
Identifier of product category in the catalog |
|
J |
Category name |
String |
Name of product category in the catalog |
|
K |
Referrer |
String |
Publisher domain on which ad was served |
|
L |
Environment |
String |
Browsing medium (web or app) |
|
M |
Device family |
String |
Device specification of user agent |
|
N |
OS family |
String |
Operating system specification of user agent |
|
O |
App ID |
String |
Identifier of app |
|
P |
App name |
String |
Specification of app |
|
Q |
Viewability |
String |
Indicates if display was viewable for at least 50% of a continuous second -1 = impression was untracked; no insight into if it was viewed 0 = impression was tracked, but not viewable 1 = impression was tracked, and was viewable |
|
R |
Marketplace revenue currency |
String |
Currency of the impression display cost |
|
S |
Marketplace revenue (local) |
Double |
Impression display cost in local currency |
|
T |
Marketplace revenue (USD) |
Double |
Impression display cost in USD currency |
|
U |
Click revenue currency |
String |
Currency of the click cost |
|
V |
Click revenue (local) |
Double |
Cost per click in local currency |
|
W |
Click revenue (USD) |
Double |
Cost per click in USD currency |
|
Question |
Answer |
|---|---|
|
How do I differentiate my AdSets from one another? |
If you have multiple AdSets under a given advertiser, they will be identified uniquely in the reports by the AdSet ID field. You can also reference the AdSet field. |
|
Why does the referrer field contain "null" or "unknown"? |
Due to legal and technical limitations, we might not receive the exact publishers' domain information (also known as blind traffic). These instances are tracked as “null” under the “referrer” field in the Log-level reports. This is a general behavior in the industry and it is common to have around 10% of traffic that falls under this definition. |
|
Why am I seeing a lot of itunes.apple.com and play.google.com? |
Our inApp displays will report as itunes.apple.com or play.google.com depending on the operating system the user has. itunes.apple.com = iOS play.google.com = Android |
|
Why am I seeing users from different countries included in these reports? |
User targeting is derived from continental data base location. Every AdSet has an account ID that is linked to a specific data base. Unless there is a country-specific geofilter applied on the AdSet, it technically can target any user in that geographical region. For example, an AdSet linked to one of our Americas data centers could target a user in any North or South American country unless it has a country-specific geofilter applied. |
|
Why am I seeing values of 0 in the category\_ID field? And "unknown" in the category\_name field? |
If your Criteo product catalog does not have category IDs mapped to specific product IDs, this will display a value of 0. Likewise, this is why "unknown" appears in the category\_name field. |
|
“Why do I sometimes see revenue related to clicks, and other times related to display? |
If the AdSet is using an adaptive optimizer or a target budget mechanism, it will show a click revenue of 0 because we are billing displays, not clicks. If you’re using a standard click-billed AdSet, you will see a click cost unless smoothing is activated. |
|
Field |
Required |
Description |
|---|---|---|
|
|
Yes |
Marketplace seller identifier for which the budget applies |
|
|
Yes |
List containing the Single-Seller template campaign ID (length = 1) |
|
|
Yes |
Total amount for the budget period (monetary value in your currency) |
|
|
Yes |
Date when the budget becomes active |
|
|
Yes |
Date when the budget stops allowing spend |
|
|
Yes |
Must be
|
|
|
Optional |
|
|
|
Response |
Unique budget identifier (
|
|
Reason |
Description |
Action required |
|---|---|---|
|
ManuallyStopped |
Campaign manually paused |
Resume via budget |
|
NoBudgetDefined |
No valid budget linked |
Create a budget |
|
NoCpcDefined |
No CPC set |
Set CPC via API |
|
NoMoreBudget |
Budget fully spent |
Create a new budget |
|
RemovedFromCatalog |
Products removed |
Restore products |
|
NotYetStarted |
Newly created |
Wait |
|
NoMoreDailyBudget |
Daily limit reached |
Wait for daily reset |
|
Other |
Internal/system issue |
Contact your Criteo team |
* If `suspendedSince` is `null` and `suspensionReasons` is empty → the campaign is active. * If `suspendedSince` is set and one or more reasons are present → the campaign is currently suspended. ## Suspending and resuming a Single-Seller campaign You do **not** pause Single-Seller campaigns directly via a campaign-level endpoint. Instead, you control campaign run state by suspending or resuming the associated **budget**. ### Suspend (pause) a campaign To stop spend for a seller, set `isSuspended: true` on the active budget:
|
Pattern |
Supported? |
Notes |
|---|---|---|
|
Single-Seller + no productSet (default) |
Yes |
All eligible products from the seller are used. |
|
Single-Seller + one
|
Yes |
Recommended pattern for SKU restriction. |
|
Multiple
|
No |
Updates replace the existing rule. |
|
|
No |
They are typically used for: * Marketplace BI dashboards and data warehouses * Scheduled exports and reporting pipelines * Seller-facing performance reports For low-latency / near real-time monitoring, use the [**MPO Real-Time Asynchronous API**](/marketing-solutions/docs/getting-realtime-mpo-statistics) instead. *** ## When to Use Standard vs. Real-Time Stats Use the **Standard Reporting API** when you need: * Aggregated metrics over longer time ranges (for example, last 30 days, last quarter) * Stable, post-processed data suitable for billing, margin analysis, and long-term trends * Scheduled batch exports into your own reporting stack Use the [**Real-Time API**](/marketing-solutions/docs/getting-realtime-mpo-statistics) when you need: * Short-window metrics (for example, last minutes or hours) * Monitoring of launches, tests, or rapid changes (budgets, activation, CPC) * Near real-time dashboards or alerts *** ## Shared Concepts ### Supported Metrics All standard MPO stats endpoints expose the same core metrics: * `impressions` – Number of times products were shown in banners. * `clicks` – Number of clicks on products. * `cost` – Amount spent for those clicks. * `saleUnits` – Number of products sold attributed to those clicks. * `revenue` – Revenue generated by attributed sales. * `cr` – Conversion rate (`saleUnits / clicks`). * `cpo` – Cost per order (`cost / saleUnits`). * `cos` – Cost of sale (`cost / revenue`). * `roas` – Return on ad spend (`revenue / cost`). Exact metric definitions and attribution rules are identical for **Multi-Seller** and **Single-Seller**. What changes is which identifier (campaign, seller, seller-campaign) you aggregate by. *** *** ## Aggregation Interval You control the aggregation granularity with `intervalSize`, typically: * **Day** – one row per day * **Month** – one row per calendar month * **Year** – one row per calendar year * **Hour** – for shorter windows; may have stricter max range Exact allowed values and maximum date range depend on your environment; see the API reference for constraints. *** ## Common Filtering Parameters All three endpoints share a common set of filters. The most important are: ### Time range * `startDate` – include events from the start of this day (inclusive) * `endDate` – include events up to the end of this day (inclusive) ### Row limit * `count` – maximum number of rows to return ### Attribution * `clickAttributionPolicy` – `SameSeller`, `AnySeller`, or `Both` (where supported) Each endpoint then adds its own identifier filters (for example, `campaignId`, `sellerId`). *** # Endpoints ## Seller Statistics **Purpose:** Performance aggregated per seller over time.
Restrict metrics to a specific advertiser (your marketplace). * `sellerId` (string, optional)
Restrict to a single seller. If omitted, returns one row per seller per interval. * `startDate`, `endDate` (date, optional)
Filter events to a given date range. If omitted: * `endDate` defaults to today. * `startDate` defaults to `endDate` (one day). * `intervalSize` (enum, optional)
Aggregation granularity: `Day`, `Month`, `Year`, and in some environments `Hour`. * `count` (integer, optional)
Maximum number of rows to return (useful for pagination or sampling). * `clickAttributionPolicy` (enum, optional)
Attribution mode: `SameSeller`, `AnySeller`, or `Both` (where supported). ### Response Shape (Conceptual) The response uses a **"columns + data"** structure like so: ```json expandable theme={null} { "columns": [ "sellerId", "sellerName", "day", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas" ], "data": [ [ "1200972", "sellerA", "2026-03-01", 14542, 48, 3.36, 0, 0.0, 0.0, null, null, 0.0 ] ], "rows": 1 } ``` * The first columns identify the seller (`sellerId`, `sellerName`) and time bucket. * The remaining columns are the metrics. For **Single-Seller** and **Multi-Seller**, the schema is identical; what differs is how you populate `sellerId` and `sellerName`from your catalog and seller mapping. *** ## Campaign Statistics **Purpose:** Performance aggregated per campaign over time.
Restrict to a specific advertiser. * `campaignId` (string, optional)
Restrict to one campaign. If omitted, returns one row per campaign per interval. * `startDate`, `endDate`, `intervalSize`, `count`, `clickAttributionPolicy`
Same semantics as for seller stats. ### Response Shape (Conceptual) ```json expandable theme={null} { "columns": [ "campaignId", "day", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas" ], "data": [ [ "168423", "2026-03-01", 3969032, 13410, 1111.295, 985, 190758099, 0.073, 1.128, 0.0, 171653.88 ] ], "rows": 1 } ``` ### Typical Use Cases * Overall performance for a Multi-Seller or template campaign * High-level reporting for commercial or product stakeholders * Sanity checks before drilling down at seller or seller-campaign level *** ## Seller-Campaign Statistics **Purpose:** Performance aggregated per (campaign, seller) pair over time.
Restrict to a specific advertiser. * `campaignId` (string, optional)
Restrict to a specific campaign (or template). * `sellerId` (string, optional)
Restrict to one seller. If omitted, you get rows across all sellers/campaigns. * `startDate`, `endDate`, `intervalSize`, `count`, `clickAttributionPolicy`
Same semantics as for the other endpoints. ### Response Shape (Conceptual) ```json expandable theme={null} { "columns": [ "campaignId", "sellerId", "sellerName", "day", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas" ], "data": [ [ "168423", "1110222", "sellerA", "2026-03-01", 14542, 48, 3.36, 0, 0.0, 0.0, null, null, 0.0 ] ], "rows": 1 } ``` ### Typical Use Cases * Per-seller performance within a multi-seller campaign * Single-Seller reporting when you want to filter on one (`sellerId`, `templateCampaignId`) pair * Feeding a seller dashboard that shows per-campaign breakdowns *** ## Multi-Seller vs Single-Seller: How to Think About IDs The endpoints are shared; what changes is how you interpret IDs: ### Multi-Seller * `campaignId` – ID of a shared MPO campaign. * `sellerId` – marketplace seller identifier managed via MPO Sellers. * Seller-campaign rows show how each seller performs inside the pooled campaign. ### Single-Seller * `campaignId` – often the template campaign ID (for high-level views). * `sellerId` – marketplace seller; still the primary key for per-seller reporting. * In some setups, a dedicated `sellerCampaignId` exists and may be used in other APIs; here you still filter by `campaignId` + `sellerId`. ### When designing your reporting model
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Show only metrics for this advertiser. |
|
No |
|
|
Specify the click attribution policy for salesUnits, revenue, CR, CPO, COS, and ROAS |
|
No |
|
|
Return up to the first count rows of data (default is all rows). |
|
No |
|
|
Filter out all events that occur after date (default is today’s date). |
|
No |
|
|
Specify the aggregation interval for events used to compute stats (default is "day"). |
|
|
|
|
Show only metrics for this seller (default all sellers). |
|
|
|
|
Filter out all events that occur before date (default is the value of
|
|
No |
|
Query Parameter |
Format |
Meaning |
|---|---|---|
|
|
|
Filter out all events that occur before date (default is the value of
|
|
|
|
Filter out all events that occur after date (default is today’s date) |
|
Query Parameter |
Options |
Meaning |
|---|---|---|
|
|
Int > 0 |
Return up to the first count rows of data (default is to return all rows available). |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Show only metrics for this advertiser. |
|
No |
|
|
Specify the click attribution policy for salesUnits, revenue, CR, CPO, COS, and ROAS |
|
No |
|
|
Return up to the first count rows of data (default is all rows). |
|
No |
|
|
Filter out all events that occur after date (default is today’s date). |
|
No |
|
|
Specify the aggregation interval for events used to compute stats (default is "day"). |
|
No |
|
|
Show only metrics for this seller (default all sellers). |
|
No |
|
|
Filter out all events that occur before date (default is the value of
|
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Show only metrics for this advertiser. |
|
No |
|
|
Show only metrics for this campaign (default all campaigns). |
|
No |
|
|
Specify the click attribution policy for salesUnits, revenue, CR, CPO, COS, and ROAS |
|
No |
|
|
Return up to the first count rows of data (default is all rows). |
|
No |
|
|
Filter out all events that occur after date (default is today’s date). |
|
No |
|
|
Specify the aggregation interval for events used to compute stats (default is "day"). |
|
No |
|
|
Filter out all events that occur before date (default is the value of
|
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Show only metrics for this advertiser. |
|
No |
|
|
Show only metrics for this campaign (default all campaigns). |
|
No |
|
|
Specify the click attribution policy for salesUnits, revenue, CR, CPO, COS, and ROAS |
|
No |
|
|
Return up to the first count rows of data (default is all rows). |
|
No |
|
|
Filter out all events that occur after date (default is today’s date). |
|
No |
|
|
Specify the aggregation interval for events used to compute stats (default is "day"). |
|
No |
|
|
Show only metrics for this seller (default all sellers). |
|
No |
|
|
Filter out all events that occur before date (default is the value of
|
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Return only budgets that pay for a given advertiser. Default is to not filter on advertiser |
integer |
No |
|
|
Return only budgets that pay for a given campaign. Default is to not filter on campaign |
integer |
No |
|
|
Return only budgets belonging to the given seller. Default is to not filter on seller. |
string |
No |
|
|
Return budgets that end after the given date. Default is today (
|
string |
No |
|
|
Return budgets that start on or before the given date. Default is to not filter on startDate. |
string |
No |
|
|
Return only budgets with the given status. Default is to not filter on status. Possible values: Archived , \*\* Current , Scheduled\*\* |
string |
No |
|
|
Return only budgets of the given type. Default is to not filter on budget type. Possible values: Capped , \*\* Uncapped , Daily\*\* |
string |
No |
|
|
Return budgets with remaining balance. Default is to not filter on balance. |
boolean |
No |
|
|
Return budgets with any positive spend. Default is to not filter on spend |
boolean |
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Filters budgets belonging to the specified seller campaign. |
|
Yes |
|
|
Returns budgets ending after the specified date (
|
|
No |
|
|
Returns budgets starting on or before the specified date (
|
|
No |
|
|
Filters budgets by their status. Possible values: Archived , \*\* Current , Scheduled\*\*. |
|
No |
|
|
Filters budgets by the specified budget type. |
|
No |
|
|
Returns only budgets with a positive balance. |
|
No |
|
|
Returns budgets with a positive spend amount. |
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Return sellers for the given advertiser Id. Default is to not filter on advertiser |
|
No |
|
|
Return sellers for the given campaign Id. Default is to not filter on campaign |
|
No |
|
|
Returns only sellers with the given
|
|
No |
|
|
Return only sellers with a specific status. Possible values: Inactive , \*\* Active\*\*. |
|
No |
|
|
Return sellers with any budget having the given state. Default is to not filter on the budget state. Possible values: Archived , \*\* Current , Scheduled\*\* |
|
No |
|
|
Return sellers with or without products in the catalog. The default is not to filter on products in the catalog. |
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Filters budgets to those owned by the specified seller. |
|
Yes |
|
|
Filters budgets to those funding the specified campaign. |
|
No |
|
|
Returns budgets ending after the given date (
|
|
No |
|
|
Returns budgets starting on or before the given date (
|
|
No |
|
|
Filters budgets by the specified status. Possible values: Archived , \*\* Current , Scheduled\*\*. |
|
No |
|
|
Filters budgets by the specified budget type. |
|
No |
|
|
Returns only budgets that currently have a remaining balance. |
|
No |
|
|
Returns budgets that have a positive spend amount. |
|
No |
|
Parameter |
Definition |
Type |
Required? |
|---|---|---|---|
|
|
Limits results to campaigns belonging to the specified seller. |
|
Yes |
|
|
Filters campaigns by the budget status. Possible values: Archived , \*\* Current , Scheduled\*\*. |
|
No |
|
|
Filters campaigns linked to the specified campaign ID. |
|
No |
|
|
Filters campaigns by the seller's status. Possible values: Inactive , \*\* Active\*\*. |
|
No |
|
Responsibility |
Tasks |
|---|---|
|
Criteo |
MPO enablement on the account; campaign / template configuration; core advertiser and campaign readiness for MPO use |
|
Marketplace |
Event collection on web and/or app; product catalog integration; seller data mapping in the feed; OAuth / API integration for ongoing operations; seller activation, budgets, bids, and statistics retrieval once onboarding is complete |
|
Field |
Description |
|---|---|
|
|
ID of the advertiser |
|
|
ID of the ad set |
|
|
Name of the ad set |
|
|
Web/Android/iOS |
|
|
The name of the ad placement |
|
Field |
Description |
|---|---|
|
|
The number of clicks driven by the add. |
|
|
The number of displays/impressions of ads served on sites through the Criteo Publisher Network. |
|
|
The amount of money spent on Criteo advertising. |
|
|
The number of completed e-commerce transactions or purchases. Attribution model pc30d |
|
|
The number of completed e-commerce transactions or purchases. Attribution model pv1d |
|
|
The amount of money generated by the online sales. Attribution model pc30d |
|
|
The amount of money generated by the online sales. Attribution model pv1d |
|
|
Cost Of Sales - the ratio between the cost generated by the campaign(s) vs. the revenue generated by the sales, figured as a percentage. Attribution model pc30d |
|
|
Cost Of Sales - the ratio between the cost generated by the campaign(s) vs. the revenue generated by the sales, figured as a percentage. Attribution model pv1d |
|
|
Return On Ad Spend - the ratio between the revenue generated and the cost. Attribution model pc30d |
|
|
Return On Ad Spend - the ratio between the revenue generated and the cost. Attribution model pv1d |
|
|
Cost Per Order - the amount of money that needs to be spent to get one order or transaction. Attribution model pc30d |
|
|
Cost Per Order - the amount of money that needs to be spent to get one order or transaction. Attribution model pv1d |
|
|
ConVersion Rate - the percentage of completed purchases compared to the clicks that occurred. Attribution model pc30d |
|
|
ConVersion Rate - the percentage of completed purchases compared to the clicks that occurred. Attribution model pv1d |
|
Field |
Description |
Optional/Required |
Type |
Default Value |
|---|---|---|---|---|
|
|
start of the period |
required |
DateTime |
|
|
|
end of the period |
required |
DateTime |
|
|
|
List of Advertiser Ids separated by commas |
required |
string of ID's separated by commas |
|
|
|
List of Ad Set Ids separated by commas |
optional |
string of ID's separated by commas |
|
|
|
Filter for Ad Set names |
optional |
string |
|
|
|
Web/Android/iOS |
optional |
string |
|
|
|
Time zone used for dates |
required |
Timezone |
|
|
|
Currency used for amounts |
required |
||
|
|
Filter the value of the placement |
optional |
string |
|
|
|
Format of the report provided in the response (json, xml, csv, xls) |
optional |
string |
CSV |
|
|
undisclosed exchanges for which we don't have the domain |
required |
string |
true |
## What's next * [Placement Category](/marketing-solutions/docs/placement-category) # Placement Category Source: https://developers.criteo.com/marketing-solutions/docs/placement-category ## **Introduction** The placement category endpoint provides transparency on which **categories** of domains your ads are being displayed on, as well provides visibility into the number of displays, clicks, and sales that have occurred via a given publisher. *** ## **How It Works** A single domain can have several categories associated with it because the single page categorization is grouped at the domain level. Also, each individual page can hold several categories. For example, a news website could have pages linked to business, sports, and entertainment.
|
Field |
Type |
Required |
Default Value |
Description |
|---|---|---|---|---|
|
|
DateTime |
Yes |
Start of the report in YY-MM-DD format |
|
|
|
DateTime |
Yes |
End of the report in YY-MM-DD format |
|
|
|
string |
Yes |
Comma separated list of Advertiser IDs in an array |
|
|
|
string |
No |
null |
Report only on the specified adset Id |
|
|
string |
No |
Report only on the specified category |
|
|
|
string |
No |
Report only on the specified domain |
|
|
|
boolean |
No |
true |
Specify if the domain dimension is displayed in the report |
|
|
Timezone |
No |
UTC |
Timezone used for dates |
|
|
string |
Yes |
CSV |
Format of the report: JSON, XML, CSV, XLS |
**Accepted values:** string of int64 / **Writeable?** N / **Nullable?** N | | `productSetId` | string | ID of the product set being boosted within the ad.
**Accepted values:** string of int64 / **Writeable?** N / **Nullable?** N | | `boostingFactor`\* | number (double) | Multiplier applied to products in the set during ad serving. A value of `1` means no boost.
**Accepted values:** positive float / **Writeable?** Y / **Nullable?** N | | `modificationDate` | string | Datetime of the last modification to this configuration.
**Accepted values:** datetime string / **Writeable?** N / **Nullable?** N | *\*Required at create/update operation*
|
Catalog Field Name |
API Field Name |
Operators Available |
|---|---|---|
|
Category 1, Category 2, Category 3 |
|
|
|
Brand |
|
|
|
Product ID |
|
|
|
Custom Label 0, Custom Label 1, Custom Label 2 , Custom Label 3, Custom Label 4 |
|
|
|
Sale Price |
|
|
* `campaignId` – the ID of your Multi-Seller MPO campaign. * `bid` – initial CPC bid for this seller in the campaign (in the campaign’s currency). ### Example response (simplified) ```json JSON theme={null} { "id": "42171358.123456", "sellerId": "42171358", "campaignId": 123456, "bid": 1.20, "suspendedSince": null, "suspensionReasons": [] } ```
* `id` is the `sellerCampaignId` (often a composite of seller and campaign). * A seller-campaign is active when: * `bid` is positive, and * `suspendedSince` is `null` (no active suspension reason). If your account already has seller-campaigns for a given seller and campaign, you can skip creation and move directly to updating bids (next step). ## Step 3 – Set or adjust bids for each seller-campaign Once the seller-campaign exists, you can update the CPC bid to control how aggressively that seller participates in the Multi-Seller campaign. ### 3.1 Retrieve the seller-campaign (optional) To confirm current configuration: ```http HTTP theme={null} GET https://api.criteo.com/{version}/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId} Authorization: Bearer
# Quick Start – Launch a Single-Seller Campaign via MPO Source: https://developers.criteo.com/marketing-solutions/docs/quick-start-launch-a-single-seller-campaign-via-mpo ## What you’ll accomplish In this recipe, you will: * Take a single seller from having **no Single-Seller campaign** to having a **live, dedicated Single-Seller campaign**. * Create the first **Single-Seller budget**, which: * Automatically creates the per-seller campaign for that seller and template (if it doesn’t exist yet). * Controls how much that seller can spend and over which dates. * Restrict products for that seller’s campaign using **`productSet`** (this is optional). * Verify the setup using both: * **Budgets** endpoints, to confirm configuration. * **Statistics** endpoints, to confirm the seller is delivering. This recipe assumes you already understand the high-level concepts in the\ [Single-Seller Campaigns – Concept Guide](https://criteo.atlassian.net/wiki/display/~g.handley/Single-Seller+Campaigns+%E2%80%93+Concept+Guide). ## Who this recipe is for This flow is intended for sellers who are a good fit for Single-Seller, typically: * **Top or strategic sellers** who can meet the minimum Single-Seller budgets, and * Sellers with **enough eligible products** in their catalog to support stable delivery. Very small or long-tail sellers with very low daily budgets are usually better handled via **Multi-Seller campaigns**, not Single-Seller. ## Prerequisites Before you start, make sure all of the following are true. ### Feature enablement #### API access Marketplace Performance Outcomes uses the same Marketing Solutions Performance Media / Campaign endpoints as your other campaigns – there is no separate “MPO API” to activate. To call `/marketplace-performance-outcomes`, your application must: * Be onboarded to Marketing Solutions with the **Campaign** domain in its scope. * Have the **Campaign Manage** permission, as described in the [onboarding checklist](/marketing-solutions/docs/onboarding-checklist#3-define-your-app-scope). #### Single-Seller feature enablement Single-Seller campaigns must be enabled on your account. Confirm with your Criteo representative that: * Your advertiser is allowed to use **Single-Seller**. * At least one **Single-Seller template campaign** exists for you. If Single-Seller is not enabled, the calls in this recipe may return authorization or validation errors. ### Template configuration * You have a **Single-Seller template campaign ID** from Criteo: * This is often referred to as `templateCampaignId`. * You must use this ID as `campaignId` in **budget calls**. * You know the **minimum per-seller budget** for this template: * For example: a minimum total budget per period, or a minimum “equivalent daily” spend. ### Seller eligibility Single-Seller is designed for sellers who can sustain **meaningful, continuous delivery**. Before using this recipe for a seller, check that: * The seller can meet the **minimum daily budget** guidelines for Single-Seller. As a rule of thumb: * **Recommended**: around **US\$20/day** for ROAS/sales goals, or **US\$10/day** for click goals. * **Hard minimums**: **US\$10/day** (ROAS/sales) and **US\$5/day** (click). * The seller is **not** a pure long-tail seller with very small or sporadic budgets. * Long-tail sellers are usually better suited to **Multi-Seller pooled campaigns**. * If you plan to use `productSet` for this seller: * The seller has at least **\~20 in-stock products** mapped correctly in the catalog. * This helps avoid **under-delivery** and `productSet` **validation errors**. ### Catalog and sellers * Your product catalog is integrated and includes `sellerName` on relevant products. * The MPO Sellers endpoints return sellers: * You can call `/marketplace-performance-outcomes/sellers` and see your sellers. * Each seller you want to onboard to Single-Seller has a corresponding `sellerId`. ### API access & permissions You have valid OAuth 2.0 client credentials and can obtain a Bearer token. Your OAuth token must include the following permissions for the advertiser portfolios used in this recipe: * **Campaigns: Read** * **Campaigns: Manage** With these permissions, your app can read the required entities (including sellers), create and update budgets, and call the reporting endpoints used in this workflow. You will need (for this recipe): * `advertiserId` * `templateCampaignId` (Single-Seller template campaign ID) * `sellerId` (you will retrieve this in Step 1) * Minimum per-seller budget for this template (from Criteo) **Estimated time:** \~30–60 minutes if all of the above are ready. ## Step 1 – Get the `sellerId` Use the MPO Sellers endpoint to find the internal `sellerId` for the seller. Example (filter by `sellerName`): **Endpoint** ```http theme={null} GET https://api.criteo.com/{version}/marketing-solutions/marketplace-performance-outcomes/sellers?sellerName={YourSellerName} Authorization: Bearer
## What's next * [MPO Real-Time Asynchronous API](/marketing-solutions/docs/getting-realtime-mpo-statistics) * [MPO Standard Reporting API](/marketing-solutions/docs/mpo-standard-reporting-api) # Single-Seller Source: https://developers.criteo.com/marketing-solutions/docs/singleseller
|
Reason |
Meaning |
Action |
|---|---|---|
|
|
Budget manually suspended |
Resume via budget
|
|
|
No active budget exists |
Create a valid budget |
|
|
No CPC set |
Set a CPC bid |
|
|
Budget fully spent |
Create a new budget for a future period |
|
|
All products removed |
Restore products in the catalog |
|
|
Newly created, not yet processed |
Wait for provisioning |
|
|
Daily spend limit reached |
No action needed; resets the next day |
|
|
Internal error |
Contact Criteo Product or R\&D |
|
Entity |
Who creates it |
What it does |
|---|---|---|
|
Campaign |
Criteo |
Top-level ad configuration; not managed via MPO API |
|
Template campaign (
|
Criteo |
Single-Seller blueprint; defines shared settings for all derived seller-campaigns |
|
Seller-campaign (
|
Created implicitly by Criteo on first budget
|
Per-seller delivery campaign; managed via budgets and
|
|
Reason |
Meaning |
Action |
|---|---|---|
|
|
Budget manually suspended |
Resume via budget
|
|
|
No active budget exists |
Create a valid budget |
|
|
Budget fully spent |
Create a new budget for a future period |
|
|
All products removed |
Restore products in the catalog |
|
|
Newly created, not yet processed |
Wait for provisioning |
|
|
Daily spend limit reached |
No action needed; resets the next day |
|
|
Internal error |
Contact Criteo Product or R\&D |
|
Endpoint |
Use case |
|---|---|
|
|
Aggregated across all sellers for a template |
|
|
Per-seller aggregation |
|
|
Per seller-campaign (most granular) |
* **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).
* **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](/retail-media/docs/balances-endpoints) 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](/retail-media/docs/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](/retail-media/docs/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](https://developers.criteo.com/retail-media/v2026.07/reference/balance/2026-07retail-mediabalances) 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](/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.
This endpoint supports data retrieval for up to three months in the past. # /2026-07/statistics/report Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/analytics/2026-07statisticsreport https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/statistics/report This Statistics endpoint provides ad set related data. It is an upgrade of our previous Statistics endpoint, and includes new metrics and customization capabilities.
This endpoint supports data retrieval for up to two years in the past. # /2026-07/transactions/report Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/analytics/2026-07transactionsreport https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/transactions/report This Transactions endpoint provides transactions id related data.
This endpoint supports data retrieval for up to two years in the past. # /2026-07/marketing-solutions/ad-sets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ad-sets Create an ad set with the provided parameters # /2026-07/marketing-solutions/ad-sets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/ad-sets Patch a list of AdSets. # /2026-07/marketing-solutions/ad-sets/{ad-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ad-sets/{ad-set-id} Get the data for the specified ad set # /2026-07/marketing-solutions/ad-sets/{ad-set-id}/audience Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-audience https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json put /2026-07/marketing-solutions/ad-sets/{ad-set-id}/audience Link or unlink an audience with an ad set # /2026-07/marketing-solutions/ad-sets/{ad-set-id}/category-bids Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-category-bids https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ad-sets/{ad-set-id}/category-bids Get the Category Bids for all valid Categories associated to an Ad Set # /2026-07/marketing-solutions/ad-sets/{ad-set-id}/category-bids Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-category-bids-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/ad-sets/{ad-set-id}/category-bids Update the Category Bids for given Categories associated to an Ad Set Patch Category Bids for one or more Categories in a single request. Partial success policy is followed. # /2026-07/marketing-solutions/ad-sets/{ad-set-id}/display-multipliers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-display-multipliers https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ad-sets/{ad-set-id}/display-multipliers Get the Display Multipliers for all valid Categories associated to an Ad Set # /2026-07/marketing-solutions/ad-sets/{ad-set-id}/display-multipliers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-sets-display-multipliers-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/ad-sets/{ad-set-id}/display-multipliers Update the Display Multipliers for given Categories associated to an Ad Set Patch Display Multipliers for one or more Categories in a single request. Partial success policy is followed. # /2026-07/marketing-solutions/ad-sets/search Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-setssearch https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ad-sets/search Search for ad sets based on provided criteria. This returns the full configuration of ad sets matching those criteria. Field projection can be used if only a subset of fields is required, instead of the full configuration. If specific fields are precised in the user prompt, use meta.fields field projection in order to query only the value of these fields, else, provide every field. # /2026-07/marketing-solutions/ad-sets/start Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-setsstart https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ad-sets/start Start the specified list of ad sets # /2026-07/marketing-solutions/ad-sets/stop Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsad-setsstop https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ad-sets/stop Stop the specified list of ad sets # /2026-07/marketing-solutions/campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionscampaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/campaigns Create the specified campaign A campaign, or in other words a marketing campaign, is an entity that defines advertising objectives and success criteria. # /2026-07/marketing-solutions/campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionscampaigns-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/campaigns Patch a list of Campaigns. A campaign, or in other words a marketing campaign, is an entity that defines advertising objectives and success criteria. # /2026-07/marketing-solutions/campaigns/{campaign-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionscampaigns-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/campaigns/{campaign-id} Get the data for the specified campaign. A campaign, or in other words a marketing campaign, is an entity that defines advertising objectives and success criteria. # /2026-07/marketing-solutions/campaigns/search Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionscampaignssearch https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/campaigns/search Search endpoint for campaigns A campaign, or in other words a marketing campaign, is an entity that defines advertising objectives and success criteria. # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers Get the collection of advertisers associated with the user. # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId} Get an advertiser. # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/ad-preview Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-ad-preview https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/ad-preview Get a preview of an HTML ad with products belonging to the provided seller • advertiserId: Valid crp advertiserId, seller belongs to provided advertiser
• sellerId: Products from given SellerId will fill the ad preview, must be existing crp sellerId
• height: height may be supplied to request a specific ad preview height. Default height: 250
• width: width may be supplied to request a specific ad preview width. Default width: 300
Ad preview api calls are capped to 1000 per day per advertiser by default. Current usage, limit, and period can be found using v2/crp/advertisers/preview-limit # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/adsets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-adsets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/adsets Get the collection of adsets associated with the advertiserId. # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-budgets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/budgets Get CRP budgets for a specific advertiser # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-campaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/campaigns Get the collection of CRP campaigns associated with the advertiserId. # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-seller-campaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/seller-campaigns Get CRP seller campaigns for a specific advertiser # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/sellers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertisers-sellers https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/{advertiserId}/sellers Create new sellers for an advertiser # /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/preview-limit Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesadvertiserspreview-limit https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/advertisers/preview-limit Get the collection of advertisers preview limits associated with the authorized user. # /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesbudgets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Return a collection of budgets filtered by optional filter parameters, **including archived budgets**. This is the endpoint to use when investigating past budget history. By default, budgets whose endDate is in the past are excluded. Use `endAfterDate` to retrieve archived budgets (e.g. `endAfterDate=2025-01-01` returns all budgets ending after that date). Use `sellerId` to filter to a specific seller — omitting it on large advertisers causes timeouts. Date filter. To find budgets that were active on a specific date, set both `startBeforeDate` and `endAfterDate` to that day. Spend. If `endAfterDate` is supplied, the spend excludes spend that happened after that date. For daily budgets, only the spend for the final day is displayed. # /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesbudgets-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Create one or more new budgets to enable spending with the given limitations. All three types of budgets can be created this way. The following constraints apply when creating a new budget. • sellerId: the seller MUST be supplied
• campaignIds: a non-empty array of campaign ids MUST be supplied
• budgetType: a budget type MUST be supplied
• amount: an amount MAY be supplied only if the type is not Uncapped and if supplied it MUST be non-negative
• startDate: a future start date MUST be supplied
• endDate: an end date MAY be supplied and if supplied MUST be greater than the start date
Other attributes MUST NOT be supplied. # /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesbudgets-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets Modify one or more existing active budgets to change their limitations or status. All three types of budgets can be modified. The following constraints apply when modifying an existing budget. • campaignIds: a non-empty subset of the original campaign ids MAY be supplied
• amount: an amount MAY be supplied only if the type is not Uncapped and if supplied it MUST be non-negative
• startDate: a future start date MAY be supplied for budgets that have not yet started
• endDate: an end date MAY be supplied and if supplied MUST be a future date greater than the start date
Other attributes MUST NOT be supplied. Adding new campaigns to a budget is not allowed. In addition, reducing the amount for a Capped budget to a value less than the current spend not allowed. # /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesbudgets-3 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId} Return a budget. For example, { "id": "1759183", "sellerId": "321392", "campaignIds": [ 143962 ], "budgetType": "Capped", "amount": 1000, "startDate": "2021-01-11", "endDate": "2021-01-12", "spend": null, "status": "Active" } A budget limits the spend of a seller for one or more campaigns. There are three types of budget:
Uncapped budgets put no limit on the total amount of spend.
Capped budgets limit the total spend to a fixed amount.
Daily budgets limit daily spend to a fixed amount.
In addition, budgets can limit the spend to a specific range of dates using the start and end date attributes. Finally a budget must be active to be used. Spend approximates the current spend against this budget. There may be a lag between when an ad is clicked and the time it accrues to the spend. Daily budgets show spend against the most recent day only. # /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesbudgets-4 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId} Modify an existing active budget to change its limitations or status. All three types of budgets can be modified. See the additional restrictions listed in the PATCH budgets endpoint. # /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesseller-campaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns Return a collection of seller campaigns filtered by optional filter parameters. If all parameters are omitted the entire collection to which the user has access is returned. Returned sellers must satisfy all supplied filter criteria if multiple parameters are used. # /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesseller-campaigns-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns Patching a collection of seller campaigns allows their bids to be modified. Each bid must be a non-negative value. Setting the bid to zero will make a seller campaign inactive. The currency used for bids will be the default currency of the campaign. # /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesseller-campaigns-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId} Return details for a seller campaign. For example, { "id": "543210.123456", "sellerId": "543210", "campaignId": 123456, "bid": 1.55, "suspendedSince": "2018-07-30T15:15:24.813", "suspensionReasons": [ "NoMoreBudget" ] } An active seller campaign is one for which the value of suspendedSince is null and the bid is positive. The currency of the bid is the bidCurrency of the associated campaign. Any active seller campaign must also have an active total (capped or uncapped) budget. It may optionally have an active daily budget as well to further limit spending. Suspension reasons: - ManuallyStopped: The Seller-Campaign has been manually paused. This is not related to the other suspension reasons. - NoBudgetDefined: No valid budget has been linked to the Seller-Campaign. - NoCpcDefined: No CPC has been set for the Seller-Campaign. - NoMoreBudget: The current budget of the Seller-Campaign has been exhausted. - RemovedFromCatalog: All the products of the Seller-Campaign have been deleted from the catalog. - NotYetStarted: The Seller-Campaign has just been created and has not yet been processed. # /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesseller-campaigns-3 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId} Patching a seller campaign allows the bid to be modified. The bid must be a non-negative value. Setting the bid to zero will make a seller campaign inactive. The currency used for bids will be the default currency of the campaign. # /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId}/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesseller-campaigns-budgets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/seller-campaigns/{sellerCampaignId}/budgets Return a collection of budgets for this seller campaign filtered by optional filter parameters. If all parameters are omitted the entire collection to which the user has access is returned, except those whose endDate is in the past. Returned budgets must satisfy all supplied filter criteria if multiple parameters are used. See the budgets endpoint for additional details. # /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomessellers https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers Return a collection of sellers filtered by optional filter parameters. If all parameters are omitted the entire collection to which the user has access is returned. Returned sellers must satisfy all supplied filter criteria if multiple parameters are used. # /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomessellers-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId} Return details for the selected seller. For example, { "id" : "123456" "sellerName": "HBogart", } # /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/budgets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomessellers-budgets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/budgets Return current (non-archived) budgets for this seller. Budgets whose endDate is in the past are excluded by default. To retrieve archived or past budgets, use the `/budgets` endpoint (GetMarketplaceSellerBudgets) with the `endAfterDate` filter instead. # /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomessellers-seller-campaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/seller-campaigns Return a collection of seller campaigns for this seller filtered by optional filter parameters. If all parameters are omitted the entire collection to which the user has access is returned. Returned sellers must satisfy all supplied filter criteria if multiple parameters are used. See the seller campaigns endpoint for additional details. # /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomessellers-seller-campaigns-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/marketplace-performance-outcomes/sellers/{sellerId}/seller-campaigns Associate an existing Seller with an existing Campaign allowing for budget creation # /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesstatscampaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/campaigns ## Dimensions Get performance statistics aggregated for _campaigns_. The campaign id appears in the output as the first column. Aggregation can be done by `hour`, `day`, `month`, or `year` aligned with the user timezone if provided. The aggregation interval size is controlled by `intervalSize`. The time interval appears in the output as the second column. ## Metrics The metrics reported by this endpoint are . | Metric Group | Description ---|--------------|------------ A | impressions | Number of times product is shown in a banner B | clicks | Number of clicks on product C | cost | Amount spent for clicks on products D | saleUnits | Number of products sold attributed to clicks E | revenue | Revenue generated by sales F | CR = Conversion Rate | salesUnits / clicks G | CPO = Cost Per Order | cost / salesUnits H | COS = Cost of Sale | cost / revenue I | ROAS = Return On Add Spend | revenue / cost The last six metrics can be computed in two ways depending on the policy to count only the sales that result from clicks on the same sellers product in a banner (same-seller) or not (any-seller). Reporting can be controlled by `clickAttributionPolicy`. The 9 (or 15) metric values appear in the output as the final 9 (or 15) columns. ## Filtering The results can be filtered by campaign, date or count. Filtering the results to events associated with a specific campaign is done by setting the `campaignId` filter parameter to the desired value. Filtering the results to events that happened in a time interval is done by setting the `startDate` and `endDate` filter parameters using the `yyyy-MM-DD` format. The start date includes all events timestamped since the beginning of that day while the end date includes events until the end of day. The maximum duration of the date range is 1 year. If the aggregation interval is `hour`, then the maximum duration of the date range is 31 days. Note that month and year aggregate values may contain partial data for the interval if filtering by date. Filtering the results to a maximum number of data rows is done by setting the `count` filter parameter. When combined with startDate this can be used to perform simple pagination. ## Response Format The representation format can be specified by MIME values in the Accept header. For now the only supported values for the accept header is `application/json` and `text/csv`. ```json { "columns": [ "campaignId", "month", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas" ], "data": [ [168423, "2019-05-01", 3969032, 13410, 1111.295, 985, 190758099, 0.073, 1.128, 0.000, 171653.880 ], [168423, "2019-06-01", 8479603, 25619, 2190.705, 740, 152783656, 0.028, 2.960, 0.000, 69741.775 ] ], "rows": 2 } ``` The JSON result is an object with three fields (`columns`, `data`, and `rows`). The “columns” array acts as the header for the data rows. The categorical dimension column comes first and consists of the campaign id. The interval column comes next and defines the aggregation period. The interval size is determined by the `intervalSize` parameter. This is followed by either nine or fifteen metrics columns. The first three metrics (impressions, clicks, and cost) always appear. The remaining depend on the `clickAttributionPolicy` parameter. The “data” array contains data rows whose values match the entries in the “columns” array. Id dimensions are numbers while name and date dimensions are strings. The metrics are JSON objects whose type is number. Some of these are natural numbers (e.g. clicks and impressions) whereas others are decimal values. A divide by zero yields null. The currency is assumed to be the local currency established by the advertiser. The “row” value is a count of the number of rows in the data array, and can be used to check the integrity of the data. Further information on the campaign or seller (e.g. the seller name) can be obtained from the existing V1 or V2 endpoints using the campaign and/or seller ID values. # /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/seller-campaigns Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesstatsseller-campaigns https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/seller-campaigns ## Dimensions Get performance statistics aggregated for _seller campaigns_.The campaign id, seller id, and seller name appear in the first three columns of the output. These are followed by the interval size column. Aggregation can be done by `hour`, `day`, `month`, or `year` aligned with the user timezone if provided. The aggregation interval size is controlled by `intervalSize`. The remaining columns are metrics. ## Metrics The metrics reported by this endpoint are . | Metric Group | Description ---|--------------|------------ A | impressions | Number of times product is shown in a banner B | clicks | Number of clicks on product C | cost | Amount spent for clicks on products D | saleUnits | Number of products sold attributed to clicks E | revenue | Revenue generated by sales F | CR = Conversion Rate | salesUnits / clicks G | CPO = Cost Per Order | cost / salesUnits H | COS = Cost of Sale | cost / revenue I | ROAS = Return On Add Spend | revenue / cost The last six metrics can be computed in two ways depending on the policy to count only the sales that result from clicks on the same sellers product in a banner (same-seller) or not (any-seller). Reporting can be controlled by `clickAttributionPolicy`. The 9 (or 15) metric values appear in the output as the final 9 (or 15) columns. ## Filtering The results can be filtered by date or count. Filtering the results to events associated with a specific campaign is done by setting the `campaignId` filter parameter to the desired value. Filtering the results to events associated with a specific seller is done by setting the `sellerId` filter parameter to the desired value. Filtering the results to events that happened in a time interval is done by setting the `startDate` and `endDate` filter parameters using the `yyyy-MM-DD` format. The start date includes all events timestamped since the beginning of that day while the end date includes events until the end of day. The maximum duration of the date range is 1 year. If the aggregation interval is `hour`, then the maximum duration of the date range is 31 days. Note that month and year aggregate values may contain partial data for the interval if filtering by date. Filtering the results to a maximum number of data rows is done by setting the `count` filter parameter. When combined with startDate this can be used to perform simple pagination. ## Response Format The representation format can be specified by MIME values in the Accept header. For now the only supported values for the accept header is `application/json` and `text/csv`. ```json { "columns": [ "campaignId", "sellerId", "sellerName", "month", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas" ], "data": [ [168423, 1110222, "118883955", "2019-05-01", 14542, 48, 3.36, 0, 0.0, 0.0, null, null, 0.0], [168423, 1110222, "118883955", "2019-06-01", 16619, 53, 3.71, 0, 0.0, 0.0, null, null, 0.0], [168423, 1110225, "117980027", "2019-05-01", 12502, 48, 3.36, 0, 0.0, 0.0, null, null, 0.0], [168423, 1110225, "117980027", "2019-06-01", 20266, 53, 3.71, 0, 0.0, 0.0, null, null, 0.0] ], "rows": 4 } ``` The JSON result is an object with three fields (`columns`, `data`, and `rows`). The “columns” array acts as the header for the data rows. The categorical dimension columns come first and include the campaign id, seller id, and seller name. The interval column comes next and defines the aggregation period. The interval size is determined by the `intervalSize` parameter. This is followed by either nine or fifteen metrics columns. The first three metrics (impressions, clicks, and cost) always appear. The remaining depend on the `clickAttributionPolicy` parameter. The “data” array contains data rows whose values match the entries in the “columns” array. Id dimensions are numbers while name and date dimensions are strings. The metrics are JSON objects whose type is number. Some of these are natural numbers (e.g. clicks and impressions) whereas others are decimal values. A divide by zero yields null. The currency is assumed to be the local currency established by the advertiser. The “row” value is a count of the number of rows in the data array, and can be used to check the integrity of the data. Further information on the campaign or seller (e.g. the seller name) can be obtained from the existing V1 or V2 endpoints using the campaign and/or seller ID values. # /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/sellers Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/campaign/2026-07marketing-solutionsmarketplace-performance-outcomesstatssellers https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/marketplace-performance-outcomes/stats/sellers ## Dimensions Get performance statistics aggregated for _sellers_. The seller id appears in the output in the first column and the seller name appears in the second. Aggregation can be done by `hour`, `day`, `month`, or `year` aligned with the user timezone if provided. The aggregation interval size is controlled by `intervalSize`. The time interval appears in the output as the second column. ## Metrics The metrics reported by this endpoint are . | Metric Group | Description ---|--------------|------------ A | impressions | Number of times product is shown in a banner B | clicks | Number of clicks on product C | cost | Amount spent for clicks on products D | saleUnits | Number of products sold attributed to clicks E | revenue | Revenue generated by sales F | CR = Conversion Rate | salesUnits / clicks G | CPO = Cost Per Order | cost / salesUnits H | COS = Cost of Sale | cost / revenue I | ROAS = Return On Add Spend | revenue / cost The last six metrics can be computed in two ways depending on the policy to count only the sales that result from clicks on the same sellers product in a banner (same-seller) or not (any-seller). Reporting can be controlled by `clickAttributionPolicy`. The 9 (or 15) metric values appear in the output as the final 9 (or 15) columns. ## Filtering The results can be filtered by seller id, date or count. Filtering the results to events associated with a specific seller is done by setting the `sellerId` filter parameter to the desired value. Filtering the results to events that happened in a time interval is done by setting the `startDate` and `endDate` filter parameters using the `yyyy-MM-DD` format. The start date includes all events timestamped since the beginning of that day while the end date includes events until the end of day. The maximum duration of the date range is 1 year. If the aggregation interval is `hour`, then the maximum duration of the date range is 31 days. Note that month and year aggregate values may contain partial data for the interval if filtering by date. Filtering the results to a maximum number of data rows is done by setting the `count` filter parameter. When combined with startDate this can be used to perform simple pagination. ## Response Format The representation format can be specified by MIME values in the Accept header. For now the only supported values for the accept header is `application/json` and `text/csv`. ```json { "columns": ["sellerId", "sellerName", "month", "impressions", "clicks", "cost", "saleUnits", "revenue", "cr", "cpo", "cos", "roas"], "data": [ [1200972, "sellerA", "2019-05-01", 14542, 48, 3.36, 0, 0.0, 0.0, null, null, 0.0], [1200972, "sellerA", "2019-06-01", 16619, 53, 3.71, 0, 0.0, 0.0, null, null, 0.0], [1200974, "sellerB", "2019-05-01", 10102, 47, 3.29, 3, 396000.0, 0.063, 1.096, 8.308E-6, 120364.741], [1200974, "sellerB", "2019-06-01", 11576, 54, 3.78, 1, 132000.0, 0.018, 3.78, 2.863E-5, 34920.634] ], "rows": 4 } ``` The JSON result is an object with three fields (`columns`, `data`, and `rows`). The “columns” array acts as the header for the data rows. The categorical dimension columns come first and include the seller id and seller name. The interval column comes next and defines the aggregation period. The interval size is determined by the `intervalSize` parameter. This is followed by either nine or fifteen metrics columns. The first three metrics (impressions, clicks, and cost) always appear. The remaining metrics depend on the `clickAttributionPolicy` parameter. The “data” array contains data rows whose values match the entries in the “columns” array. Id dimensions are numbers while name and date dimensions are strings. The metrics are JSON objects whose type is number. Some of these are natural numbers (e.g. clicks and impressions) whereas others are decimal values. A divide by zero yields null. The currency is assumed to be the local currency established by the advertiser. The “row” value is a count of the number of rows in the data array, and can be used to check the integrity of the data. Further information on the campaign or seller (e.g. the seller name) can be obtained from the existing V1 or V2 endpoints using the campaign and/or seller ID values. # /2026-07/marketing-solutions/ads/{ad-id}/product-boost Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-boost https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ads/{ad-id}/product-boost Fetch all boosting associations and configurations # /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-boost-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Fetch boosting association and configuration # /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-boost-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Create or update product boosting configuration # /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-boost-3 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/ads/{ad-id}/product-boost/{product-set-id} Delete association and configuration. # /2026-07/marketing-solutions/ads/{ad-id}/product-filter Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-filter https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ads/{ad-id}/product-filter Fetch product filtering configuration for a given ad # /2026-07/marketing-solutions/ads/{ad-id}/product-filter Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-filter-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/ads/{ad-id}/product-filter Enable product filtering for a given ad # /2026-07/marketing-solutions/ads/{ad-id}/product-filter Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsads-product-filter-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/ads/{ad-id}/product-filter Disable product filtering for a given ad # /2026-07/marketing-solutions/audience-segments Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segments https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/audience-segments Updates the properties of all segments with a valid configuration, and returns their IDs. For those that cannot be updated, one or multiple errors are returned. # /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segments-contact-list https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list Delete all identifiers from a contact list audience-segment. # /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segments-contact-list-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list Add/remove identifiers to or from a contact list audience-segment. # /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list/statistics Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segments-contact-liststatistics https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/audience-segments/{audience-segment-id}/contact-list/statistics Returns the statistics of a contact list segment. # /2026-07/marketing-solutions/audience-segments/compute-sizes Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentscompute-sizes https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audience-segments/compute-sizes Gets the size of all segments. An error is returned for those whose size calculation is not supported. # /2026-07/marketing-solutions/audience-segments/create Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentscreate https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audience-segments/create Creates all segments with a valid configuration, and returns their IDs. For those that cannot be created, one or multiple errors are returned. # /2026-07/marketing-solutions/audience-segments/delete Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentsdelete https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audience-segments/delete Delete the segments associated to the given audience IDs. # /2026-07/marketing-solutions/audience-segments/estimate-size Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentsestimate-size https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audience-segments/estimate-size Gets the size estimation of a non existent segment. An error is returned when size calculation is not supported. # /2026-07/marketing-solutions/audience-segments/in-market-brands Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentsin-market-brands https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/audience-segments/in-market-brands Returns a list with all available in-market brands that can be used to define an in-market segment. # /2026-07/marketing-solutions/audience-segments/in-market-interests Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentsin-market-interests https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/audience-segments/in-market-interests Returns a list with all available in-market interests that can be used to define an in-market segment. These in-market interests correspond to the Google product taxonomy. # /2026-07/marketing-solutions/audience-segments/search Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudience-segmentssearch https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audience-segments/search Returns a list of segments that match the provided filters. If present, the filters are AND'ed together when applied. # /2026-07/marketing-solutions/audiences Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiences https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/audiences Updates the properties of all audiences with a valid configuration, and returns their IDs. For those that cannot be updated, one or multiple errors are returned. # /2026-07/marketing-solutions/audiences/compute-sizes Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiencescompute-sizes https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audiences/compute-sizes Gets the size of all audiences. An error is returned for those whose size calculation is not supported. # /2026-07/marketing-solutions/audiences/create Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiencescreate https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audiences/create Creates all audiences with a valid configuration, and returns their IDs. For those that cannot be created, one or multiple errors are returned. # /2026-07/marketing-solutions/audiences/delete Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiencesdelete https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audiences/delete Deletes the audiences associated to the given audience IDs. # /2026-07/marketing-solutions/audiences/estimate-size Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiencesestimate-size https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audiences/estimate-size Gets the size estimation of a non existent audience. An error is returned when size calculation is not supported. # /2026-07/marketing-solutions/audiences/search Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/audience/2026-07marketing-solutionsaudiencessearch https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/audiences/search Returns a list of audiences that match the provided filters. If present, the filters are AND'ed together when applied. # /2026-07/commerce-grid/me Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/gateway/2026-07commerce-gridme https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json get /2026-07/commerce-grid/me Get information about the currently logged application # /2026-07/commerce-grid/audience-segments Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segments https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json patch /2026-07/commerce-grid/audience-segments Updates the properties of all segments with a valid configuration, and returns the full segments. For those that cannot be updated, one or multiple errors are returned. # /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/add-remove Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segments-contact-listadd-remove https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json post /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/add-remove Add/remove identifiers to or from a Commerce Grid audience segment of type Contact List. # /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/clear Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segments-contact-listclear https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json post /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/clear Delete all identifiers from a Commerce Grid audience segment of type Contact List. # /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/statistics Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segments-contact-liststatistics https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json get /2026-07/commerce-grid/audience-segments/{audience-segment-id}/contact-list/statistics Returns the statistics of a contact list segment. # /2026-07/commerce-grid/audience-segments/create Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segmentscreate https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json post /2026-07/commerce-grid/audience-segments/create Creates all segments with a valid configuration, and returns the full segments. For those that cannot be created, one or multiple errors are returned. # /2026-07/commerce-grid/audience-segments/delete Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segmentsdelete https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json post /2026-07/commerce-grid/audience-segments/delete Delete the segments associated to the given IDs. # /2026-07/commerce-grid/audience-segments/search Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/commerce-grid/segment/2026-07commerce-gridaudience-segmentssearch https://api.criteo.com/2026-07/commercegrid/open-api-specifications.json post /2026-07/commerce-grid/audience-segments/search Returns a list of segments that match the provided filters. If present, the filters are AND'ed together when applied. # /2026-07/marketing-solutions/ads/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsads https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/ads/{id} Get an Ad with its id # /2026-07/marketing-solutions/ads/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsads-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/ads/{id} Delete an Ad # /2026-07/marketing-solutions/advertisers/{advertiser-id}/ads Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-ads https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/ads Get the list of self-services Ads for a given advertiser # /2026-07/marketing-solutions/advertisers/{advertiser-id}/ads Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-ads-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/advertisers/{advertiser-id}/ads Create an Ad # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons Get the list of self-services Coupons for a given advertiser # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons Create a Coupon # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Get a Coupon with its id # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-3 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json put /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Edit a specific Coupon # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-4 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id} Delete a Coupon # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id}/preview Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-preview https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons/{id}/preview Get the preview of a specific Coupon # /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons-supported-sizes Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-coupons-supported-sizes https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/coupons-supported-sizes Get the list of Coupon supported sizes # /2026-07/marketing-solutions/advertisers/{advertiser-id}/creatives Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-creatives https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/advertisers/{advertiser-id}/creatives Get the list of self-services Creatives for a given advertiser # /2026-07/marketing-solutions/advertisers/{advertiser-id}/creatives Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionsadvertisers-creatives-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/advertisers/{advertiser-id}/creatives Create a Creative # /2026-07/marketing-solutions/creatives/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionscreatives https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/creatives/{id} Get a Creative with its id # /2026-07/marketing-solutions/creatives/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionscreatives-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json put /2026-07/marketing-solutions/creatives/{id} Edit a specific Creative # /2026-07/marketing-solutions/creatives/{id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionscreatives-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/creatives/{id} Delete a Creative if there are no ads binded to it # /2026-07/marketing-solutions/creatives/{id}/preview Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/creative/2026-07marketing-solutionscreatives-preview https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/creatives/{id}/preview Get the preview of a specific Creative # /2026-07/marketing-solutions/me Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/gateway/2026-07marketing-solutionsme https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/me Get information about the currently logged application # /2026-07/marketing-solutions/dataset/{dataset-id}/product-boost Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsdataset-product-boost https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/dataset/{dataset-id}/product-boost Fetch boosting association and configuration for a given partner # /2026-07/marketing-solutions/product-sets Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-sets https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json post /2026-07/marketing-solutions/product-sets Create a new product set # /2026-07/marketing-solutions/product-sets/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-sets-1 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/product-sets/{product-set-id} Fetch an existing product set # /2026-07/marketing-solutions/product-sets/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-sets-2 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json delete /2026-07/marketing-solutions/product-sets/{product-set-id} Remove a product set # /2026-07/marketing-solutions/product-sets/{product-set-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-sets-3 https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json patch /2026-07/marketing-solutions/product-sets/{product-set-id} Patch an existing product set # /2026-07/marketing-solutions/product-sets/{product-set-id}/product-filters Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-sets-product-filters https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/product-sets/{product-set-id}/product-filters Fetch product filtering usages for a given product set # /2026-07/marketing-solutions/product-sets/dataset/{dataset-id} Source: https://developers.criteo.com/marketing-solutions/v2026.07/reference/reco/2026-07marketing-solutionsproduct-setsdataset https://api.criteo.com/2026-07/marketingsolutions/open-api-specifications.json get /2026-07/marketing-solutions/product-sets/dataset/{dataset-id} Fetch product sets of a given dataset # Marketing Solutions API Changelog Source: https://developers.criteo.com/marketing-solutions/changelog/changelog Release notes and announcements for the Criteo Marketing Solutions API. Versions are released twice a year, in January and July.
## What's next * [API responses](/retailer-integration/docs/api-responses) * [API parameters](/retailer-integration/docs/api-parameters-1) # API Parameters Source: https://developers.criteo.com/retailer-integration/docs/api-parameters-1 These parameters are valid for all event types and should be included in all ad requests wherever applicable # Global Criteo Parameters ## `criteo-partner-id` **Example**: `12345` **Description**: The key that corresponds with your specific partner ID within Criteo. This ID will be provided by your technical account manager. **Required**: Yes *** ## `retailer-visitor-id` **Example**: `39573958738533503` **Description**: A unique unauthenticated UserID that is persistent across sessions on the same device. For Android apps, we recommend using the [AdvertisingIdClient API](https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient.Info), and for iOS, the [advertisingIdentifier](https://developer.apple.com/documentation/adsupport/asidentifiermanager/advertisingidentifier). If it is set as a first party cookie, it should be set as a cookie with an expiration date (maximum 13 months) and not as a session cookie. The lifetime of the cookie must be at least 30 days with longer lifetimes being more effective for attribution. **Required**: Yes
## What's next * [Homepage](/retailer-integration/docs/homepage) * [Search pages](/retailer-integration/docs/search-page) * [Search bar dropdown](/retailer-integration/docs/search-bar-dropdown) * [Category pages](/retailer-integration/docs/category-page) * [Category flyout](/retailer-integration/docs/category-flyout) * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # API Responses Source: https://developers.criteo.com/retailer-integration/docs/api-responses ## Response Format * **JSON format**: The API response is in JSON format. * **Response content**: The response will contain: * **placements**: Information about where ads should be placed. * **list of products**: A list of products to be shown. * **beaconURLs** : URLs for tracking events, detailed in [Beacon URLs](/retailer-integration/docs/legacy-universal-beacons). * **Display formats**: For display formats, the response may include extra information such as rendering details and links to image or video files. Refer to [ad formats overview](/retailer-integration/docs/format-overview) for examples for each format. * **API response structure**: For a detailed description of the API response structure with examples, please refer to the specific format pages in our Ad rendering section. *** ## Breaking Down the API Response Let's take a closer look at the structure of the API response, breaking it down into its components: ```json theme={null} { "status": "OK", "placements": [ { "viewHome_API_desktop-InGrid": [ { "format": "sponsored_products", "products": [ { "ProductId": "14567", "ParentSKU": "14567P", "OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=wIGSZXHwMFfCseG77HQd7SOaa5ItlchfEV7FsVRFvOvgCGeZNp4PqqdyMqxupiThhgJKvudYpqpi2qQjLshpQLDUSU91x_Cjx5XcX8nh40S5kaxVRk3hme-iiwO9yA8xoZpGo_6NMh4Hik96Dp6KGLSB7V1peSCN34LwnicW-3lpd6HrCirUltMP6KDMNCASCJAC2QCCoygwvbX34niecaFID9gsFPkj3gV4dZRDGjZM9GtQbWp7U-E-k4aKjRZy4prcGaQZCUcSY_e1F9yjchB_zrZMeGiNbBiA2eJ-UonqowH6CYjLdqBlO7aHpC9igyDOTh4eb1G1PX_8tBeKJFKi5JRXEALqnXns4_OD9XRqPwJY0mHLkgDDVCopXr9ecWAC_X0UyBy_GfJd79U2hVl6WZKdmXgIhNjeh3eanlk&ev=4", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=bay40713qtFIdj5P3YUhlfmJUf3bROAa3nby5U-aG8oJFEZO97wjWJ636jKfXNwwvPJxrgYvdcz3zEz2evMvaHNA0H4JriwRyTbqtFHXX1LtPCIQBibPujZpj-3s_yU9kP8SK0Th-KP9_nGXZI2b7QljQaSx8O0-xDdchB59AIBWKq3QSWcnF9Vewy-QfXUDio8q-3w1xgNHXWvPk_uhZGkaY9VTVMQINJBCT8bvxW0GMaYu0vAoIlaac1dKEC580Jzfw35iE3-LtX7w5CLlRaThsZxpWkDcmF0gxACGQg9lQCmGYevs5ePQ79dqB3ZuMIpWjXVTSwJTTvDc81hgnui1GoCN-8IjAt3zKKE3YZp7hDyxgV277J2IjQwWOhE8sBnl6B-ctSmPnp3HEzFFnqPiG5-9Iu-jy3Z9aeE5UF8kRAG1OBmfoH79xUPytz_n&ev=4", "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=HvNOO3VNgpKc4t6hdzi5OAX7aDUv4sYuvdcTL5pUPE-XcJvJKB9WA6U8cq-1VS2XYZo86Pcxj3SErB8R0eIwlLCYDIF2CZziNqca05mYyzZS9x4fRJRQgsOP0kbde6nLQ0S6z0Ea5tiL_4IlFcZ5hB6MNE1QCvmQdYS03i8Gku5Z74pxdw02QTywvhNvHZx8kJM4bwxL_KodVHjUQPXdwVzqdmUL2zeR4psWq3sLxym3Ep0ggsC89yD0yaVfZq4TDe1E59aDSszAWF3D7DgLlNJn2lhSSbhKpAJ_CnRWuW85vdtlyKzkAjf4Uqifp5CeGv9ea7B07SmGrR5d_-U7s9nOgphrLbTr91MvhCWSp0kuDEr8x9g3J6LmGzuLcM8Kbhx0LqaQkFDue1O1X-7LY9ducQKiaL7OLmkdIKX9urZBZeqSVyeqyqrs6D8PgcnObN80v6Lyo9xxsBsB5IMFig&ev=4", "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=wa79g8gomUj1xr_Krt1d4PNDKNe7Z9UMNndzrp1fMOR0zM_mowG2NiTkL6RtRYtcTaTULrRn9Uooy5rgED3l6Pf3X8gQTx2-YkPD3H0j8yvzbR4xg7SUTjSiEf_rebYfDCAHm39wt_WI6Q2yzJ8BxKdeCJBLXqA7nC4j4EqQZMbZbJ8RFSapMc0WrzQQwoPHZOCWN0KBvGTw3xC-cKjFE_7hdThHUlfIpGnuBjoGZxyQEbVjrcKKpIGkgO8gSrY-oR0KF5kvr2KroG1RFjthJtrJmRwL6cSlCk9E0HZb7wB-kjEHkXmHGtshpIOs2TIar4qbO49tGbCvxMezm7aSYEChwxAn1nHzqyDvzQUNvesnD6yymkV8wiqzj_X55uJD5dgB2otncgc-tqClKWjDUTi3g5uWPskEuZsRkcGU8sN3oMsdDhBmYf-rt6nVWUiAGLvlaumN-vcikE-KGurgHg&ev=4", "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=yqlwecnAoAcbFsxAXvx18BXQIwjUPEXgk98r3SFucMNY_RgF8izSxEJ34yjJV8EmU6j6IdXvV97At15ctkGsZ2UyUb_B4nBd9V5TTSMLYsleiVAUDa7xZmv4gnpjRBD9AZWaICw0AVOd_uBMVNN_jqenDBVcqeQw6nYARfP3T_C1jt-MkEPjKJx2PXDsWjfUFsMu0DSVoHxp17KMH4BsOOXObYVDTRrle3VogbXiQDaQ84M5Xk0QQC05z2Wp58ntk5Y44eXn7WBlLKor9QbCxSe-ESzzOP2tK5UOCkowZXI2vd2uLdTTuoBMMSkuiYlVjeLqZ7-LxO2hyT6QHJ3kQhhunCPi5t1oVmxASV1UHD94TOCUso4CbPjlT7-TDomzIgnOkXQgvjNxrV4OiSqCEZxltZlM-KUHzlfUAW6ucNNSqmdaaP9dFHNT9Pcziicui79ymAtYSzidQcE3y10xew&ev=4" } ], "rendering": "", "OnLoadBeacon": "//b.us5.us.criteo.com/rm?fid=1205&hl_qs_cmp=5uA4RAAyB4_gprioo3H-TBRN1xWe0MfgzXEjDuXPJRxh43LMFIqbvqmUpWL-X1QaLZsBnjLZmQOO8VDv8AygNKeBIrAOdc3BAt58fPXXmvpZ1X6RIwlB9ABNmCB43n9uUhqdEWeaVl03KA3L6Erk36jfiK4dJH6JwLEeIj5rUmr77DYYcqwDazIQ_-rVIABST9nVzoqvJ4spgBJ1sx0H6r_IrbD2m2GquySbzP5gA1TaSn1ZshWlpVU_N0-VwQYGIVVDlORAMWV-WUV0IBWDciC92ygwabmVl2VQrZirzdEAXDR3Y8mgd8DDtwmEbSdgf0AhF65RIhr06ZfgFMSQtXGJPLhoXibnWaj9UKxnUuCLQtjxeMBaT4Wj_qSTy13Cnzy5b7hU36GPd0nt4O44L2sC4BcoyUlZGwoM-iSCDQekIsiWyQINJERV-mzvx9lnCzThW6g85leDyWRy-ypa19Qykz_jP8lWFgB_QLit5jrW7jNDUZGN3QJwFIsBlur7VQueQ4D4CY_b9WNm4tNT9poaGyfas7X9bALmCGStKFSEcGfyEQsuivryHobe7zhNHYSSew_erOiS_gjRffOUHw&ev=4&criteopartnerid=108341&action=page&origc=A&pid=a0396133-15e5-4d8d-a0d7-7e636a0c9629&rn=96592&rm_e=0sSztFiVbHNTsuwnq1PB8pqDUAnR6K4NdhFvWiYIq46QV070UizTxdway_uMmQbJGIHCAk0ZsvRTcBKEPcv6hGrkQC0PfFdL7rRy-ESWSHrMsZn7-9KuKYThNMCgkbDzP1pKiEBh_MrkPbvTaPZBKm9KqW3zIzVDp4v8DgIiAe0-5fhKlVsNPATbNaBedHtDfZhzNyCRnVisUpFQUifH9NRcIAxn7xfaFM7ZzvDheiI2S3Eq4cfBzRDRAXU_aCA0DLOq9pRvyLuzT-QFDpmI3A", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=nZujoEOA40DwXsc-kV2o_ygnxWqQwguOzRYIKHC7LJ4Nj1jBk8k5rgTQ3b8GtfylnH6eB7y4ggvPyWft8SlXxwWH08y4GhwC-1rsq0fWbLx9F_LjVF3gdtaa_UQ5PvpjyWCLyPL5kJaj9Mbud8aXX9_7HgVjBlO6lAvEkiElMoTUzfUhRLzlBdSxYePuAOBilAFMtJ3abkHgmowMLKaK1a4tVBoK0YHexHMZ0zONVqOXjwYqx19-hgRcUyFQ6uCulio9LRmFSlflBkEWiNRQ-AHOB2vVwkkE5xOgKcEN8XWRLz1b-hYfn5ECK1Gff0D9JM6eLD1EOOSNB0jt8LPxPSG5u48q4CLAIK59MYDJXIkEJ3nS9b_OYpJ8GoDFfuB5&ev=4", "OnClickBeacon": "" } ] } ] "page-uid": "7f0b8394-f87f-438f-bf4a-b2aeae1e3144" } ``` *** ### Response Components 1. **`status`** * Type: `string` * Values: `OK` (for successful responses) or an error type. * Example: `"status": "OK"` 2. **`placements`** * Type: `array` * Description: An array of placement objects, each representing a specific ad placement on the page. 3. **`page-uid`** * Type: `string` * Description: A GUID value identifier for each ad request. * Example: `"page-uid": "7f0b8394-f87f-438f-bf4a-b2aeae1e3144"` *** ### Placement Object Each placement object contains the placement Name as the single key for the object, e.g., `viewCategory_API_desktop-inGrid`. Inside each placement, we have: * **`Format`** * Type: `string` * Description: The type of ad, e.g., `sponsored_products`. * **`Products`** * Type: `array` * Description: An array of product objects. * **`Rendering`** * Type: `string` * Description: rendering details used for commerce display ads. * **`OnLoadBeacon`** * Type: `string` * Description: URL to be called when the whole placement is loaded. * Example: `"OnLoadBeacon": "//b.us5.us.criteo.com/rm?fid=1205&hl_qs_cmp=&ev=4&criteopartnerid=108341&action=page&origc=A&pid=a0396133-15e5-4d8d-a0d7-7e636a0c9629&rn=96592&rm_e=abc123def4"` * **`OnViewBeacon`** * Type: `string` * Description: URL to be called when the placement is viewed according to IAB guidelines. * Example: `"OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` * **`OnClickBeacon`** * Type: `string` * Description: URL to be called when the placement is clicked. This is only used on commerce display ads, and it is typically triggered on clicks on the ad's image as opposed to the product inside the ad. * Example: `"OnClickBeacon": ""` *** ### Product Object Each product object contains: * **`ProductId`** * Type: `string` * Example: `"ProductId": "14567"` * **`ParentSKU`** * Type: `string` * Example: `"ParentSKU": "14567P"` * **`Beacons`** * **`OnLoadBeacon`** * Type: `string` * Description: URL to be called when the product is loaded. * Example: `"OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` * **`OnViewBeacon`** * Type: `string` * Description: URL to be called when the product is viewed according to IAB guidelines. * Example: `"OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` * **`OnClickBeacon`** * Type: `string` * Description: URL to be called when the product is clicked. * Example: `"OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` * **`OnBasketChangeBeacon`** * Type: `string` * Description: URL to be called when the product is added to the basket. * Example: `"OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` * **`OnWishlistBeacon`** * Type: `string` * Description: URL to be called when the product is added to the wishlist. * Example: `"OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=abc123def4&ev=4"` *** ## Monitoring the Auction Latency The API response includes a `Server-Timing` header which indicates how many **milliseconds** the auction took to run. This can be used to monitor server latency and break the auction part from the full round trip between ad request and response. #### Sample Request ```shell theme={null} curl -I "https://d.eu.criteo.com/delivery/retailmedia?criteo-partner-id=108341&retailer-visitor-id=456&customer-id=789&page-id=viewSearchResultApiDesktop&event-type=viewSearchResult&keywords=drink" ``` #### Response headers ```shell theme={null} HTTP/2 405 date: Mon, 31 Mar 2025 14:19:56 GMT server: Kestrel access-control-expose-headers: Server-Timing allow: GET timing-allow-origin: * server-timing: total;dur=1.2 strict-transport-security: max-age=31536000; preload; ``` In this example, the auction took 1.2 ms to run. *** ## Product Array Verbosity Levels Criteo supports two verbosity levels: * **Minimum verbosity** * Contains: `ProductId`, `ParentSKU`, beacons (`OnLoadBeacon`, `OnViewBeacon`, `OnClickBeacon`, `OnBasketChangeBeacon`, `OnWishlistBeacon`). * **Full verbosity** * Contains: All information from minimum verbosity plus additional details necessary to render the ad. All details are reflected from the [product feed parameters](/retailer-integration/docs/product-feed-parameters). Here is an example of a product object in full verbosity: ```json theme={null} { "ProductName": "Product 16823", "ProductId": "16823", "ProductPage": "//b.us5.us.criteo.com/rm?dest=https%3a%2f%2ftilt-dummy-retailer.preprod.crto.in%2fpdp%2f%3fid%3d16823&sig=1-OxTyYEct2uXeVQw334Q7rhli3hjJSfL-t1eGN0YS-2A&rm_e=uel8HURJNMmUz12YtgzGAeSR-psXmQFLCnVtykXin5b5LlMOlwR9k1w4PnZ93nTwLSLRM8h_OVK_nPLkK84uY4wBFzIx8x9AxzThTINQ0fpTsiJt_tTMuHfyLNG47gWwg5f6dDZons5DMKmZEjVsNAGmsiLF7YpZb8lFAmqaKyx8B9qIZJatI7ApL7VCCO1NAv6bvz6EQ1tvPDcZc6kY7cw5uLT5egrtd3Nupj5vJ6R_PQy-jmS5rEcmViA_Yf5AcP-teeD_wY3x59nlISoZP-sLqIksWuUr0QRfF8Z6DnR3ZQzunCi5PONmLtM1zSgOCHFj4fyf-A3GbbLe1kJdNyQtS7PZAsR04DDYAg5QEMzJoGcZGS7VVH_h5bLnF4dArQuIUamTFePufu7tmYxQvA&ev=4", "Image": "https://static.criteo.net/images/dummyretailer/glob_prod_img.png", "Rating": "-1", "Price": "69.00", "ComparePrice": "69.00", "Shipping": "0", "ParentSKU": "16823", "ClientAdvertiserId": "1205", "AdvertiserId": "17902833", "RenderingAttributes": "{\"brand\":\"retailer brand 1\",\"issellersku\":\"0\",\"mapViolation\":\"0\",\"numberOfReviews\":\"0\",\"promolabel\":\"Promo Badage blackFriday\",\"rating\":\"2\",\"shippingCost\":\"0\",\"taxonomy_text\":\"fresh foods>fruits>bananas\"}", "OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=qfD_DnfhuYEwJlj-_k6q9vq3rdUT2fgm1U5Srs1XDjS_39fWoZiJx37WMTlWfHNA-8GlrIi71W1MM4_cU_3kzxoNYzoPKWR0mFaKYJE-p5owUCOIv4-MBbjlAWCV2SlSN3xE3C7MMhZQ8IX6w1OrYPBowzevmAB0Wx3NvcvhrIILIeDQllspyDbSWlOkR-yCQ4wML_zpcAGS5AK2g-UhJrHp_eSfNK6FE92cd2W7tXnAvOr0S_TJES6-osdVfqAcaGyWFlZ7R9Wj5YJQEQizkbg8KQBBTVpaqyI0VjuQJWGtKve9i525uiAW5DVQqIqnh-M6e7zwbP_A3A8IW3rDBE1mkNoYG6bC3em7viLzrTqMKvxBItREk7tkBvj835iu-7fXjayMkHvGXxwbHLdbwQ&ev=4", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=09rCkvAHsrPsZb5M3XQAkVv3Eyk5EZgzcBZuD-SQRT12HynrMYmKnN4bcb5cN2xyWxO8SWnn8HiTEyO5m4xtCorqbG137zd8yPbvztI6ZbUwmwoU2injhkF4LDwMMFMSD8Y93F3dU6wwQlSdeaoeorNat4ka1mnNFLfNgHhREArA5cinPg-MExTIFeJ9BDUg6eKUH6dklezn_j-l-46554KUvaGVLWMoryzy-3tuXDDRFNA-JuUUMzwr-P3EvFw3WECVLDd5YqiQQIV3I3_IQhzSbk0g3L7bJP_rOBQv204U_3X_HYsoMyartqLJMSZ4zP4h_7zZB7fpPODoxVS_vGFNvYN71XeIIMxy0jFJDjvstu2CLo-K4aRVXLKaRR0iCm-ET61GpLPhsOsG_zrAhA&ev=4", "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=MZkmRRi7n5KyhcMFLsf13Qbhf0EwjnF4fERMLUS7N12_OCRXcfTXb2oQJxgIbW0UaFzHpiGR-hZ6w7yXToa9F9KnvlQ1RUhpVsVTHx0WgbtM3RVkw-XRheFJQWPqZZlLTpu0wFd_4L75iVhpzLpuCD9ZJKOJ2bawqjexZd2GmejGMtUtOUmZqxPD-SlXNAJ5lHAOi3hQ4Y4i6aDSFjA03pNXw-f9G4Pg9IQqNMzeN7rC4_gU0gTrpwmq3GvVSlp-6CtZEgZ5zGSbiRULe0hJyGcXXtlVb-y2VoDhTRa6tCb5_4XK3H7vZGYhFYBdMIort7ocWJNfL6SxKXrsGVMAfd4uakLn5M7luXowhnKKfGIzDPIw1K1FKp6XmWxd19QBMPFWLFzBladVoAgDmysFJg&ev=4", "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=iOGO2y360EsftIgtVtiVHh-SDsf3eE54JVltobiLr4M-sHkWrkErFbvMzvfe41lA2thRTR2kWl0mI4boIKb5sV27rUgDUNsKbhhEaDSVlVVRgayPm7M2jqiYW8fP1f7vTDKLqVCamHeHVkqCVoqGdZoQs_9IsoKLeNbjDS0EE-kl3UK8V1i6hD3zvTQJq9_jACnUttSmO6HN2M_i149DacstUZlOt7_U1JJ7W45b88PFQtYJAqkIX8Sq2t6k9qCaYNlPA1Jg3IIMLq5iRs8IaJw9Mk5dGz6mQAo9fiPPKLIQvZF0OJdIQAEiJ-RA4M-6OYRiMiRv8LvzqQPQlrrKyuAyF3ymPOuX_19vkLmWjpcthAmHGV4lbyjTJ0isZMhSP3v5yyBZ0A_zBTvXmJgevA&ev=4", "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=HbZtVCkIeMSvyPh6LXzeA9Cm-e1MGxY13Oi40WSQp5B3Qy_w7EmqQO9garQ0gLHdKN99Zr-pfHZXR6TwlupMYeJ5ALP6UoT2hElxZP5dbXPmZqxiyWbap2IP-18rzkSLAeBnF1vey4jsFTqFGj50A2nDUpEmt9XvYgKBdwUrPvzchXZAMW1aLSz9uz6oycliNYR7Ca866dNd8vA9VzFiU-UNHXgWhRyjyhgiwUeVom4GrzzI95e6R--PzF5PURGaJ3CDWKcVQTKrN8_lx4G3DBTSq0WQEiAKhP4b_Z1-QDrFjbWEwaAOzPh3V5OXQLOzF1zkJ21w_LEmjLaywfoDviS0YaPUoHJsOwp0JX489avZEhy11cW5YuhS3D09AudNqmarl2G3Mg6gYpiOqpDqow&ev=4" } ``` The default verbosity level can be set up by your technical account manager, but it can be changed at anytime using the `verbosity` parameter in the API calls with values `min` or `full`. See the [API parameters](/retailer-integration/docs/api-parameters-1) page for more details. *** ## Beacon Endpoints The beacon endpoint will point to different data centers determined by an automatic load balancer. This will typically be reflected on its subdomain. * **Format**: `b.[datacenter].[region].criteo.com/rm` * **Examples**: * Europe: `b.fr3.eu.criteo.com/rm?rm_e=[unique-token]&ev=4` * Americas: `b.us5.us.criteo.com/rm?rm_e=[unique-token]&ev=4` *** # API Error Responses If an API call is malformed or unable to send a valid response, the API will return a 200 HTTP status with an error message. For requests with incorrect or missing parameters, the response will include `'status': 'Error'` with an array of `'errors'`. ## Example Error Response ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Missing required param page-id", "Missing required param event-type", "Missing required param criteo-partner-id", "Could not convert parameter criteo-partner-id to an integer", "Could not determine a valid event type from the event-type parameter" ], "page-uid": null } ``` The following list, while not exhaustive, covers most error messages you may encounter. Tracking those messages is recommended to identify potential implementation errors. *** ## Possible Error Messages ### Expected one or many numerical values greater than \[or equal to] 0 **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=123" \ --data-urlencode "event-type=trackTransaction" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "page-id=trackTransaction" \ --data-urlencode "item=abc|def|ghi" \ --data-urlencode "price=249.99|200|400" \ --data-urlencode "quantity=a|b|c" \ --data-urlencode "transaction-id=123458abc" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** The parameter `quantity` has non-numeric values. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "quantity: Expected one or many integer values greater than 0" ], "page-uid": null } ``` *** ### Expected array parameters to contain the same number of items **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=123" \ --data-urlencode "event-type=trackTransaction" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "page-id=trackTransaction_API_mobile" \ --data-urlencode "item=abc|def|ghi" \ --data-urlencode "price=249.99|200|400" \ --data-urlencode "quantity=3|1" \ --data-urlencode "transaction-id=123458abc" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** The number of elements in `item` and `quantity` do not match. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Expected array parameters to contain the same number of items" ], "page-uid": null } ``` *** ### Required parameter `[parameter name]` was not of the expected format: `[error]` **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=123" \ --data-urlencode "event-type=viewItem" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "page-id=viewItem_API_mobile" \ --data-urlencode "item=abc" \ --data-urlencode "price=299,00" \ --data-urlencode "availability=1" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** `price` incorrectly formatted with a comma as a decimal separator. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Required param price was not of the expected format: Expected one or many numerical values greater than 0" ], "page-uid": null } ``` *** ### Could not convert parameter `criteo-partner-id` to an integer **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=abc" \ --data-urlencode "event-type=viewItem" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "page-id=viewItem_API_mobile" \ --data-urlencode "item=abc" \ --data-urlencode "price=299.00" \ --data-urlencode "availability=1" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** The parameter `criteo-partner-id` is always an integer. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Could not convert parameter criteo-partner-id to an integer" ], "page-uid": null } ``` *** ### Could not determine a valid event type from the `event-type` parameter **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=123" \ --data-urlencode "page-id=viewItem_API_mobile" \ --data-urlencode "event-type=viewItem" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "item=abc" \ --data-urlencode "price=299.00" \ --data-urlencode "availability=1" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** The parameters `event-type` and `page-id` are switched. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Could not determine a valid event type from the event-type parameter" ], "page-uid": null } ``` *** ### Missing required parameter `[parameter]` **Sample call:** ```bash theme={null} curl -X GET "https://d.us.criteo.com/delivery/retailmedia" \ --data-urlencode "criteo-partner-id=123" \ --data-urlencode "event-type=viewItem" \ --data-urlencode "page-id=viewItem_API_mobile" \ --data-urlencode "retailer-visitor-id=123" \ --data-urlencode "customer-id=456" \ --data-urlencode "item=abc" \ --data-urlencode "price=299.00" \ --data-urlencode "nolog=1" \ -H "Referer: www.criteo.com" \ -H "X-Forwarded-For: 123.456.789.012" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" ``` **Error:** One or many required parameters for this `event-type` are missing. **Sample response:** ```json theme={null} { "status": "Error", "placements": [], "errors": [ "Missing required param availability" ], "page-uid": null } ```
***
## What's next * [Authentication tokens](/retailer-integration/docs/using-tokens) * [API parameters](/retailer-integration/docs/api-parameters-1) * [Ad request best practices](/retailer-integration/docs/requesting-ads-best-practices) # Basket Page Source: https://developers.criteo.com/retailer-integration/docs/cart-page # Definition The basket page displays **the contents of a user’s current shopping cart**, until the order is placed. *** # Parameters ## `event-type` **Value**: `viewBasket` **Description**: Indicates to the API that this is a view basket event. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements (if any) to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewBasket_API_desktop`, `viewBasket_API_mobile`, `viewBasket_API_iOS`, `viewBasket_API_android`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewBasketApiDesktop`, `viewBasketApiMobile`, `viewBasketApiAios`, `viewBasketApiAa`. **Required**: Yes *** ## `item` **Description**: The list of SKUs in the cart. Must match the parameter ID in the feed. Multiple items should be separated by a pipe `|` or `%7C` (URL encoded). In basket pages, these are used for targeting. Include all item ids in the cart, regardless of whether or not they are sponsored. **Examples**: * `123|456|789` * `123%7C456%7C789` **Required**: Yes *** ## `quantity` **Description**: The pipe-separated quantities of each SKU within the user’s basket. **Examples**: * `4|1|2` * `4%7C1%7C2` **Required**: Yes *** # Sample Calls
## What's next * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Category Flyout Source: https://developers.criteo.com/retailer-integration/docs/category-flyout # Definition A category flyout is a window that appears when a user hovers over different category options from the main browse menu. Each change in category shown in the window will require its own API call, as the desired category changes. *** # Parameters ## `event-type` **Value**: `viewCategoryMenu` **Description**: Indicates to the API that this is a category flyout event. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewCategoryMenu_API_desktop`, `viewCategoryMenu_API_mobile`, `viewCategoryMenu_API_android`, `viewCategoryMenu_API_iOS`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewCategoryMenuApiDesktop`, `viewCategoryMenuApiMobile`, `viewCategoryMenuApiAios`, `viewCategoryMenuApiAa`. **Required**: Yes *** ## `category` **Description**: The category or taxonomy of the page that the user is browsing. This value should match the `product_type_key` value in the products feed. **Examples**: * Category ID, full breadcrumb style: `123>4567>89012` * Category ID, end-node-only style: `89012` * Category name style: `Computing>Keyboards and Mice>Mice` **Required**: Yes *** ## `page-uid` **Description**: This value is returned within the response of the initial call made on page load. By storing this value and including it in subsequent `viewCategoryMenu` event calls, Criteo is able to link the events to the initial ad request. **Example**: `545d9a70-f096-4568-b4b9-8f2f32a452d4` **Example Workflow for`page-uid`** : 1. User arrives at the homepage, generating a `viewHome` ad request with a unique `page-uid`. 2. User browses/hovers over categories, generating `viewCategoryMenu` calls. 3. Each `viewCategoryMenu` call must include the initial `page-uid` from the first `viewHome` call. **Required**: Yes *** # Sample Calls
## What's next * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Category Pages Source: https://developers.criteo.com/retailer-integration/docs/category-page # Definition Category pages typically display a collection of products that belong to a specific category or group. Category pages are divided into three types: * **Browse/Category**: A category page that displays a product grid. * **Merchandising**: A category landing page *without* a product grid. * **Deals**: A page for dedicated deals/offers, which might include products from several categories. *** # Parameters ## `event-type` **Value**: `viewCategory` **Description**: Indicates to the API that this is a category request. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewCategory_API_desktop`, `viewMerchandising_API_mobile`, `viewDeals_API_android`, `Category_API_iOS`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewCategoryApiDesktop`, `viewMerchandisingApiMobile`, `viewDealsApiAios`, `viewCategoryApiAa`. **Required**: Yes *** ## `category` **Description**: The category or taxonomy of the page that the user is browsing. This value should match the `product_type_key` value in the products feed. See more details [here](/retailer-integration/docs/product-feed-parameters#product_type_key). **Examples**: * Category ID, full breadcrumb style: `123>4567>89012` * Category ID, end-node-only style: `89012` * Category name style: `Computing>Keyboards and Mice>Mice` **Best Practices**: * Category ID is preferred over category name to avoid issues with typos, punctuation, and accented letters (especially in non-English languages). * If opting for category name: * The category name is case insensitive. * Spaces between the separator (`>`) are ignored. **Required**: Yes *** ## `item` **Description**: The list of SKUs that are organically shown on the page in the grid or list. Must match the parameter `id` in the feed (See details [here](/retailer-integration/docs/product-feed-parameters#id)). Multiple items should be separated by a pipe `|` or `%7C` (URL encoded). Used for reporting and for organic deduplication, if enabled. **Examples**: * `123|456|789` * `123%7C456%7C789` **Required**: Recommended, but not required. *** ## `parent-item` **Description**: Only use this if parent SKUs are being passed. Must match the parameter `item_group_id` in the feed (See details [here](/retailer-integration/docs/product-feed-parameters#item_group_id)). Multiple parent items should be separated by a pipe `|` or `%7C` (URL encoded). For SKUs that do not have parent SKUs, `NULL` should be sent instead. Used for reporting and for organic deduplication, if enabled. **Examples**: * `12345P|NULL|456789P` * `12345P%7CNULL%7C456789P` **Required**: Recommended if the ecommerce platform uses parent items *** ## `list-size` **Description**: The total number of organic items on the page. Preferably, it should match the number of item IDs sent in the `item` parameter. **Required**: Recommended *** ## `page-number` **Description**: Represents the page number for either paginated results or scroll fold if products are loaded dynamically. This parameter can be used for result deduplication, by limiting the number of products shown on each page. **Example**: `3` **Required**: Recommended *** ## `filters` **Description**: Corresponds to the filters applied by the shopper on the results. See the filter section for details on how to use this parameter. **Examples**: * `(price,le,100)` * `(color,eq,blue)` **Required**: Recommended. If not used, the ads will not follow the selected filters and might result in a poor user experience. *** # Sample Calls
## What's next * [Category flyout](/retailer-integration/docs/category-flyout) * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Commerce Display Grid Duet Source: https://developers.criteo.com/retailer-integration/docs/commerce-display-grid-duet This guide provides the specifications and technical details for the Commerce Display Grid Duet format rendering. # Introduction **Commerce Display Grid Duet** is an in-grid commerce display unit combining branding assets with a consecutive product tile.
|
|
Parameters |
Description |
|---|---|---|
|
|
required:
maxBytes:
extensions:
width:
height:
safeZoneWidth:
|
Background image that can be used for desktop and mobile (mobile field can be hidden through override if needed) |
|
|
required:
maxChars:
|
Text description of the Desktop background image for ADA compliancy purposes. |
|
|
required:
maxBytes:
extensions:
width:
height:
|
Background image of mobile ad |
|
|
required:
maxChars:
|
Text description of the Desktop background image for ADA compliancy purposes. |
|
|
required:
|
URL user is redirected to upon clicking on CTA button |
|
|
required:
Option 1:
Option 2:
|
Defines where the link opens: same tab (
|
|
|
required:
|
App URL user is redirected to upon clicking on CTA button from App environment |
|
|
required:
maxChars:
|
Text of CTA button |
|
|
default:
|
Text color of CTA button |
|
|
default:
|
CTA button background color |
|
|
maxChars:
|
Legal text (Desktop: next to CTA; Mobile/App: always visible) |
|
|
maxChars:
|
Legal text (Desktop: on hover “i” icon; Mobile/App: always visible) |
|
|
default:
Option 1:
Option 2:
|
Defines light or dark display mode for better viewing experience |
*** ### Grid-Based Scaling Presets These presets define the image scale based on standard grid tile dimensions: **Mobile Grid** When the device is mobile and the tile width is between 140 and 180 pixels, and the height is between 257 and 390 pixels: * the image is displayed at 26% scale (390 by 390 pixels). * The Retailer safety zone is 140 px by 258 px. * Brand safety zone is 140 px by 195 px. * Each component placeholder is 140 px by 31 px. **Regular Grid** For tile widths between 180 and 500 pixels and heights between 300 and 500 pixels: * the image is displayed at approximately 33% scale (500 by 500 pixels). * The Retailer safety zone is 180 px by 330 px. * Brand safety zone is 180 px by 250 px. * Each component placeholder: 180 px by 40 px. **Large Grid** * When the tile width is greater than 270 pixels and the height is greater than 500 pixels * the image is displayed at 50% scale (750 by 750 pixels). * The Retailer safety zone is 270 px by 495 px. * Brand safety zone is 270 px by 375 px. * Each component placeholder: 270 px by 40 px.
#### Non-compliant Tile Dimension If the grid tiles do not match any of the above scenarios, other solutions can be determined and implemented as long as the Retailer safety zone and Brand safety zone is respected within the image. *** ### Alternative Mobile Layout This layout variant is optimized for mobile devices and single column product grids/lists and includes a horizontal product slider beneath a branded background area. #### Background Image * The background image size is 1280 by 400 pixels. * It is divided into two sections: * A **branding zone** at the top * A **product zone** positioned below the branding zone * The image is fully responsive: * It scales proportionally based on the width of its parent container. * As the width decreases, the height decreases proportionally. * The image is never cropped. #### Product Slider Behavior * Products are displayed in a horizontally scrollable slider. * **Navigation dots** appear below the slider to indicate the user’s current position: * One dot is shown for each product. * The dot representing the visible product is darker to show its active status. * If there is only one product, no dots are displayed.
|
Detail |
Legal text |
More info |
|---|---|---|
|
Height |
40 pixels |
Dynamic, based on text length |
|
Padding |
5 pixels on both the left and right sides of the tile |
8 pixels, all around |
|
Font |
Roboto Regular, 12 pixels |
Roboto Regular, 12 pixels |
|
Max characters |
90 |
180 |
**Alternative Mobile Layout** * Legal and More info text will be displayed together * "See less" / "See more" option for expanded or contracted view of text * **Padding:** 8 pixels, all sides * **Font:** same as Grid layout * **Max characters:** same as Grid layout * **Background:** Displayed over a colored layer (the layer color adapts based on color mode)
## What's next * [Commerce Display Spotlight](/retailer-integration/docs/commerce-display-spotlight) * [Commerce Display Grid Shelf](/retailer-integration/docs/commerce-display-grid-shelf) * [Branding Display Grid Solo](/retailer-integration/docs/branding-display-grid-solo) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) # Commerce Display Spotlight Source: https://developers.criteo.com/retailer-integration/docs/commerce-display-spotlight This guide provides the specifications and technical details for the Commerce Display Spotlight format rendering. # Introduction The **Commerce Display Spotlight** is a responsive horizontal commerce display unit combining branded assets with products.
## Mobile
*** # Response Keys
|
|
Parameters |
Description |
|---|---|---|
|
|
required:
maxBytes:
extensions:
width:
height:
safeZoneWidth:
safeZoneHeight:
|
Background image of desktop ad |
|
|
required:
maxChars:
|
Text description of the Desktop background image for ADA compliancy purposes. |
|
|
required:
maxBytes:
extensions:
width:
height:
|
Background image of mobile ad |
|
|
required:
maxChars:
|
Text description of the Desktop background image for ADA compliancy purposes. |
|
|
required:
|
URL user is redirected to upon clicking on CTA button |
|
|
required:
Option 1:
Option 2:
|
Defines where the link opens: same tab (
|
|
|
required:
|
App URL user is redirected to upon clicking on CTA button from App environment |
|
|
required:
maxChars:
|
Text of CTA button |
|
|
default:
|
Text color of CTA button |
|
|
default:
|
CTA button background color |
|
|
maxChars:
|
Legal text (Desktop: next to CTA; Mobile and App: always visible) |
|
|
maxChars:
|
Legal text (Desktop: on hover “i” icon; Mobile and App: always visible) |
|
|
default:
Option 1:
|
Defines light or dark display mode for better viewing experience |
#### Main layout (recommended) * Desktop asset renders at **67% scale**. * The banner height is fixed to the **safety zone height (134px)**. * The Product Zone moves **below the banner**, with a suggested height of **136px** * Total format height: **270px**\ Please note that the presence of optional elements such as the CTA button, “More info”, and "Legal" components may increase the overall height of the banner.
#### Alternative layout * The Branding Zone has a **fixed width of 384px**. * The Product Zone occupies **no more than 50% of the total width**, and is sized to fit all product content. * If product content does not fit: * The Product Zone height may adjust automatically (up to **300px**), or * The main layout above may be applied instead
### Call-to-Action (CTA) Button * **Max characters:** 25 * **Size:** 150 x 30 pixels * **Font:** Roboto Regular, 12 pixels * **Margin & Alignment** * Desktop and Tablet layout: * 8 pixels below branding zone & below button * When there is no legal text: Centered below branding zone * If legal text enabled: left aligned and 10 pixels to the right of the button * Mobile Layout: 8 pixels above and 10 pixels below button * Mobile Layout: 10 pixels below navigation dots and 10 pixels below button ### Legal Text and More Info **Desktop and Tablet layout**
|
Detail |
Legal text |
More info |
|---|---|---|
|
Location |
below branding zone (right of CTA button if enabled) |
contained in interactive overlay |
|
Height |
Dynamic, based on text length |
Dynamic, based on text length |
|
Padding |
|
8 pixels, all around |
|
Font |
Roboto Regular, 12 pixels |
Roboto Regular, 12 pixels |
|
Max characters |
90 |
180 |
|
Background |
Displayed over a colored layer (the layer color adapts based on color mode) |
Same as legal text |
## What's next * [Commerce Display Grid Duet](/retailer-integration/docs/commerce-display-grid-duet) * [Commerce Display Grid Shelf](/retailer-integration/docs/commerce-display-grid-shelf) * [Branding Display Grid Solo](/retailer-integration/docs/branding-display-grid-solo) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) # Favorites Page Source: https://developers.criteo.com/retailer-integration/docs/favorites-page # Definition Favorites/wishlist pages are pages where users save their favorite products to be viewed later. *** # Parameters ## `event-type` **Value**: `viewFavorites` **Description**: Indicates to the API that this is a favorites/wishlist event. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return (if any) for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewFavorites_API_desktop`, `viewFavorites_API_mobile`, `viewFavorites_API_android`, `viewFavorites_API_iOS`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewFavoritesApiDesktop`, `viewFavoritesApiMobile`, `viewFavoritesApiAios`, `viewFavoritesApiAa`. **Required**: Yes *** ## `item` **Description**: The list of SKUs that are saved as favorites. Must match the parameter ID in the feed. Multiple items should be separated by a pipe `|` or `%7C` (URL encoded). **Examples**: * `123|456|789` * `123%7C456%7C789` **Required**: Yes *** ## `parent-item` **Description**: Only use this if parent SKUs are being passed. Must match the parameter `item_group_id` in the feed (See details [here](/retailer-integration/docs/product-feed-parameters#item_group_id)). Multiple parent items should be separated by a pipe `|` or `%7C` (URL encoded). For SKUs that do not have parent SKUs, `NULL` should be sent instead. Used for reporting and for organic deduplication, if enabled. **Examples**: * `12345P|NULL|456789P` * `12345P%7CNULL%7C456789P` **Required**: Recommended if the eCommerce platform uses parent items *** ## `price` **Description**: The list of prices in the same order as the items. Prices should be separated by a pipe `|` or `%7C` (URL encoded). These need to be the unitary prices (price of an individual item). **Examples**: * `29.99|15.49|9.99` * `29.99%7C15.49%7C9.99` **Required**: Yes *** ## `quantity` **Description**: The pipe-separated quantities of each SKU within the user’s favorites/wishlist. **Examples**: * `4|1|2` * `4%7C1%7C2` **Required**: Yes *** # Sample Calls
## What's next * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Feed Best Practices Source: https://developers.criteo.com/retailer-integration/docs/feed-best-practices ## Filters Retailers can enhance the user experience by [integrating filters in the product catalog](/retailer-integration/docs/product-feed-parameters#filters) and [applying them dynamically](/retailer-integration/docs/filtering) onsite when selected by users. Almost all modern e-commerce product listings allow the shopper to select filters to narrow down the results to the most relevant products. Criteo can mirror any filters provided by your business, but for that, we need to know which filters apply to which products. In particular, make sure to reflect the filters you business provide in the product catalog you send to Criteo. All available filters that can be applied onsite should be included in the product feed and shared with us.
## What's next * [Feed upload guide](/retailer-integration/docs/product-upload-guide) * [Product Importer API guide](/retailer-integration/docs/product-importer-guide) # Filters Source: https://developers.criteo.com/retailer-integration/docs/filtering # Definition Filters in Criteo's Retail Media Delivery API are designed to mirror the filtering options that shoppers use when browsing product listings. This allows for a more targeted and relevant ad delivery based on specific product attributes. Each filter has three main properties: * name * operator * value *** ## Name This can be one of the standard filters (see below), or a custom filter that you've set up within the product feed. *** ## Operator The condition applied to the filter. Supported operators include: #### `eq`: equal to #### `gt`: greater than #### `lt`: less than #### `ge`: greater than or equal to #### `le`: less than or equal to #### `in`: membership in a list #### `neq`: not equal #### `nin`: not in *** ## Value The specific value(s) to filter on. This can be either a text string for filters like brand, or a numerical value for filters like price. The value(s) must match the exact values passed within the corresponding field of the product feed. **Note:** `eq` , `neq`, `in`, and `nin` operators can support multiple values, while the others only support single value. *** # Standard Filters Criteo supports the following standard filters: * **brand** * **price** * **rating** These filters are pulled directly from the corresponding fields in the product feed. Additional custom filters must be configured within the product feed's `filters` field. Please refer to the [Criteo Feed Parameters](/retailer-integration/docs/product-feed-parameters#filters) page for more details. *** # Examples ## Single Filter * `filters=(price,le,500)`: Only allow products that are less than or equal to \$500. * `filters=(color,eq,blue)`: Only allow products whose value for the "color" custom filter is "blue". * `filters=(brand,in,sony,hp,dell)`: Only allow products from the brands Sony, HP, or Dell. *** ## Multiple Filters * `filters=(brand,in,sony,hp,dell),(price,lt,500)`: Only allow products from the brands Sony, HP, or Dell that also cost less than \$500. * `filters=(price,ge,100),(price,le,500)`: Only allow products with a price between \$100 and \$500, inclusive.
## What's next * [Ad request best practices](/retailer-integration/docs/requesting-ads-best-practices) # Formats Overview Source: https://developers.criteo.com/retailer-integration/docs/format-overview This page provides an overview of all the Ad formats available to render Ads in the RM Criteo solution # Introduction This page provides an overview of various digital ad formats available in the Criteo Retail Media solution. Each format is tailored to meet specific advertising goals, (maximizing visibility, increasing user engagement, or seamlessly integrating ads into a platform's user experience). There are three main categories of formats. * **Onsite Display** including: * Commerce Display Grid Duet, * Commerce Display Spotlight, * Commerce Display Grid Shelf, * Branding Display Grid Solo, * Branding Display Spotlight Solo. * The **Sponsored Products** format, * The **Video formats**, including: * The Commerce Video Spotlight format, * The Branding Video Standout format, * The Commerce Video Grid Duet format. *** # Onsite Display Formats
|
Format Type |
Legacy Formats Name |
New Formats Name |
|---|---|---|
|
Commerce Display |
Flagship |
Commerce Display Spotlight |
|
Commerce Display |
Showcase |
Commerce Display Grid Shelf |
|
Commerce Display |
Butterfly |
Commerce Display Grid Duet |
|
Commerce Display |
Branded Header (Mobile) |
Now integrated into the new formats |
|
Commerce Display |
Interactive Header (Mobile) |
Now integrated into the new formats |
|
Display Banners |
Digital Shelf Talker |
Branding Display Grid Solo |
|
Display Banners |
Display Panel |
Branding Display Spotlight Solo |
|
Display Banners |
IAB Banners |
IAB Banners (unchanged) |
## What's next * [Onsite Display (New)](/retailer-integration/docs/onsite-display-new-formats) * [Onsite Display (Legacy)](/retailer-integration/docs/onsite-display-legacy) * [Sponsored products](/retailer-integration/docs/sponsored-products) * [Video Formats](/retailer-integration/docs/video-formats) # Homepage Source: https://developers.criteo.com/retailer-integration/docs/homepage # Definition The homepage is **the initial landing page of the website**. When making API calls for the homepage, the parameters described below should be used. *** # Parameters ## `event-type` **Value**: `viewHome` **Description**: Indicates to the API that this is a homepage request. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewHome_API_desktop`, `viewHome_API_mobile`, `viewHome_API_android`, `viewHome_API_iOS`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewHomeApiDesktop`, `viewHomeApiMobile`, `viewHomeApiAios`, `viewHomeApiAa`. **Required**: Yes *** # Sample Calls
## What's next * [Search pages](/retailer-integration/docs/search-page) * [Search bar dropdown](/retailer-integration/docs/search-bar-dropdown) * [AI assistant](/retailer-integration/docs/ai-assistant) * [Category pages](/retailer-integration/docs/category-page) * [Category flyout](/retailer-integration/docs/category-flyout) * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Integration process Source: https://developers.criteo.com/retailer-integration/docs/integration-process An overview of the integration process using the Direct API method ## Overview To leverage all features offered by Criteo's Retail Media platform, it is necessary to integrate with the **Retail Media ad delivery system.** The Direct Ad Server integration entails three main steps that are detailed in this documentation: 1. Requesting ads 2. Rendering ads 3. Tracking ads
## What's next * [Glossary](/retailer-integration/docs/rm-glossary) # Introduction Source: https://developers.criteo.com/retailer-integration/docs/introduction-1 Sharing your catalog with Criteo is the first step for a succesful integration
|
Feature |
Feeds |
Product Importer API |
|---|---|---|
|
Data Format |
XML, CSV, JSON |
JSON |
|
Ingestion Speed |
Slower, due to file processing |
Faster, enabling almost real-time updates |
|
Automation |
Requires manual uploads or scheduling |
Fully automated via API endpoints |
|
Flexibility |
Limited |
High, with granular update capabilities |
|
Use Case |
Suitable for small catalogs or periodic updates |
Designed for large catalogs and updates |
## What's next * [Feed upload guide](/retailer-integration/docs/product-upload-guide) * [Product feed parameters](/retailer-integration/docs/product-feed-parameters) * [Product feed examples](/retailer-integration/docs/product-feed-examples) * [Product Importer API Guide](/retailer-integration/docs/product-importer-guide) * [Dataset parameters](/retailer-integration/docs/dataset-parameters) * [Product Dataset Examples](/retailer-integration/docs/product-dataset-examples) # Lookup Files Source: https://developers.criteo.com/retailer-integration/docs/lookup-files # Introduction Lookup files serve as an auxiliary resource in your product feed system, providing a flexible solution for incorporating additional information that might not be included directly in the main product feed. These files are particularly useful when you need to supplement the existing feed with extra data without altering its fundamental structure. *** # Key Characteristics of Lookup Files ## Purpose * **Supplemental data**: Lookup files are intended to store additional information that, for various reasons, cannot be directly added to the main feed. This can include extended descriptions, custom attributes, or any other data that enhances product listings. ## Storage * **Location on Criteo's SFTP**: By default, Criteo’s SFTP servers contain a specific folder named `/vlookup` where lookup files should be stored. This standardized location ensures that Criteo systems can reliably access and integrate these files into the broader feed processing workflow. ## File format * **CSV file requirement**: The lookup file must be formatted as a CSV (Comma-Separated Values) file. This format is widely supported and allows for straightforward handling of tabular data. * **Separator**: It is recommended to use a semicolon (`;`) as the separator in lookup files. This helps avoid common issues with comma-separated data, such as conflicts arising from commas within data fields. ## Content structure * **SKU ID and extra fields**: The primary column should be the SKU ID, which uniquely identifies each product. This ID should match exactly with the SKU IDs used in the main product feed to ensure proper linkage. Following the SKU ID, each additional column should represent a separate field containing the supplemental data. *** # Best Practices * **Consistency in SKU IDs**: Ensure that SKU IDs in the lookup file exactly match those in the main product feed. Any discrepancies can lead to issues in data merging and utilization. * **Regular updates**: Keep the lookup file updated in sync with changes in the product feed. This alignment is crucial for maintaining the accuracy and relevance of the data presented to Criteo's systems. * **Secure and structured data handling**: When updating the lookup file on the SFTP server, make sure to follow secure data handling protocols to prevent unauthorized access and ensure data integrity. Using lookup files effectively allows you to expand the depth and breadth of product information available for your campaigns without overcomplicating the primary feed structure, thereby enhancing both performance and manageability. *** # Example File To illustrate a sample lookup CSV file as described, we'll create a file that includes columns for SKU ID, Store ID, Price, and Tracking Code. This file will use a semicolon (`;`) as the separator, adhering to the recommendation for lookup files. Here’s how the sample CSV content might look: ```csv csv theme={null} sku_id;store_id;price;custom_filter 12345;001;29.99;CF12345A 23456;002;49.99;CF23456B 34567;003;19.99;CF34567C 45678;004;59.99;CF45678D ``` ## Breakdown of Each Column: * **sku\_id**: This is the unique identifier for each product. It must match the SKU ID used in the main product feed. * **store\_id**: Represents a unique identifier for the store or location where the product is available. * **price**: The selling price of the product at the specified store. * **custom\_filter**: An extra filter that can be sent in ad calls to allow only specific products to show up pages like special sales or deals. The columns in this example are just for demonstration purposes. The lookup file that you send can contain any extra data that you wish to include. You can tailor the columns to fit your specific needs, adding any additional fields that provide valuable context or information for your product listings. ***
## What's next * [Feed best practices](/retailer-integration/docs/feed-best-practices) # Onsite Display (New) Source: https://developers.criteo.com/retailer-integration/docs/onsite-display-new-formats This page gives an overview of the new Onsite Display Formats and maps the changes with the legacy formats ## Overview
|
Format Type |
Legacy Formats |
New Formats |
|---|---|---|
|
Commerce Display |
Flagship |
Commerce Display Spotlight |
|
Commerce Display |
Showcase |
Commerce Display Grid Shelf |
|
Commerce Display |
Butterfly |
Commerce Display Grid Duet |
|
Commerce Display |
Branded Header (Mobile) |
Now integrated into the new formats |
|
Commerce Display |
Interactive Header (Mobile) |
Now integrated into the new formats |
|
Display Banners |
Digital Shelf Talker |
Branding Display Grid Solo |
|
Display Banners |
Display Panel |
Branding Display Spotlight Solo |
|
Display Banners |
IAB Banners |
IAB Banners (unchanged) |
## What's next * [Commerce Display Grid Duet](/retailer-integration/docs/commerce-display-grid-duet) * [Commerce Display Grid Shelf](/retailer-integration/docs/commerce-display-grid-shelf) * [Branding Display Grid Solo](/retailer-integration/docs/branding-display-grid-solo) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) * [Commerce Display Spotlight](/retailer-integration/docs/commerce-display-spotlight) # Order Confirmation Page Source: https://developers.criteo.com/retailer-integration/docs/order-confirmation-page # Definition The order confirmation page is **the page where the user is taken right after completing a purchase**. *** # Parameters ## `event-type` **Value**: `trackTransaction` **Description**: Indicates to the API that this is an order confirmation event. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements (if any) to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `trackTransaction_API_desktop`, `trackTransaction_API_mobile`, `trackTransaction_API_iOS`, `trackTransaction_API_android`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `trackTransactionApiDesktop`, `trackTransactionApiMobile`, `trackTransactionApiAios`, `trackTransactionApiAa`. **Required**: Yes *** ## `item` **Description**: The list of SKUs ordered. Must match the parameter ID in the feed. Multiple items should be separated by a pipe `|` or `%7C` (URL encoded). Include all items in the order, regardless of whether they are sponsored or not. **Examples**: * `123|456|789` * `123%7C456%7C789` **Required**: Yes *** ## `price` **Description**: The list of prices in the same order as the items. Prices should be separated by a pipe `|` or `%7C` (URL encoded). These need to be the unitary prices (price of an individual item). Criteo will multiply these prices by the `quantity` parameter to compute the total order value. **Examples**: * `29.99|15.49|9.99` * `29.99%7C15.49%7C9.99` **Required**: Yes *** ## `quantity` **Description**: The pipe-separated quantities of each SKU within the user’s order. **Examples**: * `4|1|2` * `4%7C1%7C2` **Required**: Yes *** ## `transaction-id` **Description**: The unique order ID of the purchase. **Example**: `1841xva0ha8` **Required**: Yes *** ## `currency` **Description**: Currency code of the transaction. Only needed if the purchase can be done in different currencies; otherwise, it will fall back to the retailer's standard currency. Should be a valid [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. **Examples:**: * `USD` * `EUR` **Required**: Mandatory only if multiple currencies are allowed *** # Reporting Discounts in the OCP API Call When a promotion applies a discount (e.g., “*buy 1 get 1 for 40% off*”), the `unit_price` should reflect the average price shared across the paid items. ### Example * A customer buys 2 items, normally priced at \$24 each. * One of them is effectively discounted under the promotion “*buy 1 get 1 for 40% off*”. * To calculate the `unit_price`, we do: (24 + (0.6 × 24)) / 2 = 19.20 * Then the retailer reports `unit_price` as `19.20` in the OCP API call. *** # Sample Calls
## What's next * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Organic Add-To-Cart Events Source: https://developers.criteo.com/retailer-integration/docs/organic-add-to-cart-events # Definition Although the API request works exactly like any other page type, `add-to-cart` is not an actual page view. It is used when **the product card on pages other than PDPs allows adding products to the cart** (e.g., `add-to-cart `button on search results).
## What's next * [Filters](/retailer-integration/docs/filtering) # Integration Introduction Source: https://developers.criteo.com/retailer-integration/docs/overview Learn more about the Criteo Retail Media Ad Delivery System and how to integrate with it # Welcome
## What's next * [Integration process](/retailer-integration/docs/integration-process) * [Glossary](/retailer-integration/docs/rm-glossary) # Product Details Page Source: https://developers.criteo.com/retailer-integration/docs/product-details-page # Definition A product details page (PDP) shows the details of a single product or multiple products under the same parent ID. *** # Parameters ## `event-type` **Value**: `viewItem` **Description**: Indicates to the API that this is a PDP request. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return (if any) for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewItem_API_desktop`, `viewItem_API_mobile`, `viewItem_API_iOS`, `viewItem_API_android`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewItemApiDesktop`, `viewItemApiMobile`, `viewItemApiAios`, `viewItemApiAa`. **Required**: Yes *** ## `item` **Description**: SKU IDs corresponding to the product(s) on the PDP. To send multiple products, separate values with a pipe (`|`). The order of values must match the order used in `price` and `availability`. **Example (single product)**: `123-ab` **Example (multiple products)**: `123-ab|456-cd|789-ef` **Required**: Yes *** ## `parent-item` **Description**: Only use this if parent SKUs are being passed. If so, this value should match what is being sent in the `item_group_id` field of the product feed. **Example**: `123` **Required**: Recommended if the eCommerce platform uses parent items *** ## `price` **Description**: Current price of the product (with discount, if any). When sending multiple products, provide one price per product separated by a pipe (`|`), in the same order as `item`. **Example (single product)**: `34.99` **Example (multiple products)**: `34.99|42.21|38.99` **Required**: Yes *** ## `availability` **Description**: Stock status of the product. Send `1` if in stock, `0` if out of stock. When sending multiple products, provide one value per product separated by a pipe (`|`), in the same order as `item`. **Example (single product)**: `1` **Example (multiple products)**: `1|0|1` **Required**: Yes *** ## `category` **Description**: For PDP calls, this parameter passes an explicit category used for both ad-serving and Served Category reporting. If this field is not present, Criteo will default to the primary taxonomy of the SKU passed in the `item` parameter. If passed, this value should match the `product_type_key` value in the product feed. See more details [here](/retailer-integration/docs/product-feed-parameters#product_type_key).
## What's next * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) # Product Feed Examples Source: https://developers.criteo.com/retailer-integration/docs/product-feed-examples ## CSV / TSV To create a comprehensive CSV product feed sample incorporating all the parameters discussed in [Feed parameters](/retailer-integration/docs/product-feed-parameters), we structure the CSV to include the headers with corresponding example values for each parameter. This sample illustrates how to structure your data for upload to Criteo. Here's an example of what the CSV might look like: ```csv CSV theme={null} id,title,description,link,image_link,additional_image_link,sale_price,price,gtin,mpn,product_type,product_type_key,brand,item_group_id,google_product_category,availability,filters,seller_id,seller_name,regiondata,product_rating,number_of_reviews,is_buybox,cross_sellers_product_id 12345-123seller,"Red Men's T-Shirt Size L","A classic red T-shirt perfect for casual wear.","http://www.example.com/products/red-mens-t-shirt-size-l","http://www.example.com/images/red-t-shirt.jpg","http://www.example.com/images/red-t-shirt-back.jpg","25.99","29.99","012345678905","RT12345","Men>Clothing>T-Shirts","1>3>25","Adidas","12340","Apparel & Accessories > Clothing > Shirts & Tops","In Stock","Color=Red|Blue,Size=S|M|L|XL","123seller","Top Fashion","{'4126':{'Price':25.99,'Quantity':6}","4.5","10",true,12345 12345-999seller,"Red Men's T-Shirt Size L","A classic red T-shirt perfect for casual wear.","http://www.example.com/products/red-mens-t-shirt-size-l","http://www.example.com/images/red-t-shirt.jpg","http://www.example.com/images/red-t-shirt-back.jpg","24.99","29.99","012345678905","RT12345","Men>Clothing>T-Shirts","1>3>25","Adidas","12340","Apparel & Accessories > Clothing > Shirts & Tops","In Stock","Color=Red|Blue,Size=S|M|L|XL","999seller","Alt Fashion","{'4126':{'Price':24.99,'Quantity':3}","4.4","8",false,12345 23456-456seller,"Blue Women's Jeans","Comfortable blue jeans with a modern fit.","https://www.example.com/products/blue-womens-jeans","https://www.example.com/images/blue-jeans.jpg","https://www.example.com/images/blue-jeans-side.jpg","45.99","49.99","987654321098","BW23456","Women>Clothing>Jeans","4>10>22","Levi's","23450","Apparel & Accessories > Clothing > Pants","Out of Stock","Color=Blue|Black,Size=4|6|8|10|12","456seller","Jeans Boutique","'789':{}, '1011':{}","3.8","25",true,23456 34567,"Green Women's Scarf","Soft and stylish green scarf.","http://www.example.com/products/green-womens-scarf","http://www.example.com/images/green-scarf.jpg","","17.99","19.99","234567890123","GS34567","Women>Accessories>Scarves","5>11>23","Gucci","","Apparel & Accessories > Clothing Accessories > Scarves & Shawls","In Stock","","","","","4.7","40",true,34567 45678,"Black Men's Wallet","Elegant black leather wallet.","https://www.example.com/products/black-mens-wallet","https://www.example.com/images/black-wallet.jpg","","54.99","59.99","345678901234","BM45678","Men>Accessories>Wallets","6>12>24","Prada","","Apparel & Accessories > Clothing Accessories > Wallets & Money Clips","In Stock","","","","","4.9","15",true,45678 ``` *** ### CSV Breakdown * **`id`**: Unique identifier for each product variant. * **`title`**: The product's name as displayed on the website. * **`description`**: A brief description of the product. * **`link`**: URL to the product's detail page. * **`image_link`**: Main image URL of the product. * **`additional_image_link`**: URL for additional product images. * **`sale_price`**: How much you charge for your product during a sale. * **`price`**: Current product price, not including sales. * **`gtin`**: Global Trade Item Number, a unique identifier for products within the global marketplace. * **`mpn`**: Manufacturer Part Number. * **`product_type`**: Category breadcrumb in a hierarchical format. * **`product_type_key`**: Corresponding category IDs matching the `product_type`. * **`brand`**: Manufacturer or brand name. * **`item_group_id`**: Identifier for related product variants (e.g., different sizes or colors of the same product). * **`google_product_category`**: Google's taxonomy classification for the product. * **`availability`**: Current stock status of the product. * **`filters`**: Custom filter values for the product. * **`seller_id`**: Identifier for the seller on a marketplace. * **`seller_name`**: Name of the seller on a marketplace. * **`regiondata`**: Store-specific availability, optionally with pricing. * **`product_rating`**: The average customer rating for the product, scaled typically from 1 to 5. * **`number_of_reviews`**: The total number of customer reviews for the product. * **`is_buybox`**: Identifies the buybox winner for seller SKUs * **`cross_sellers_product_id`**: any ID that links all items as the same item despite having different sellers (This can be GTIN, MPN) *** ### Additional Notes * **Column order:** The order of columns in the CSV does not affect the processing. You can arrange the columns in any order that suits your workflow or system requirements. * **Field formatting:** Use double quotes for fields that contain commas, special characters, or embedded double quotes. For fields containing embedded double quotes, ensure each double quote is represented by two double quotes (e.g., `"Example ""quoted"" text"`). * **Protocols:** Always include the protocol (`http://` or `https://`) in URLs to ensure they are correctly processed. * **Commas in fields:** Do not use commas within fields. If you need to separate elements within a field, use alternative separators like vertical bars `|` or semicolons `;`. * **Image links:** Ensure that image URLs are accessible and conform to specified criteria such as resolution and file size. The `image_link` must specify a valid image content type (e.g., image/png, image/gif, image/jpeg). * **Character encoding:** The CSV file should be encoded in UTF-8 to support international characters and special symbols correctly. This sample CSV is designed to be illustrative and may need to be adjusted based on the specific requirements and systems used by Criteo and your eCommerce platform. *** ## XML Here's how the XML version of the feed above might look. We'll add `custom_label` tags which are commonly used to group products in custom ways that aren't covered by standard product attributes. ```xml expandable theme={null}
## What's next * [Lookup files](/retailer-integration/docs/lookup-files) * [Feed best practices](/retailer-integration/docs/feed-best-practices) # Product Feed Parameters Source: https://developers.criteo.com/retailer-integration/docs/product-feed-parameters ## Introduction This page provides a comprehensive list of fields that can be included in your product feed. Recommended fields are not mandatory but help streamline campaign management, improve performance, and enhance the shopper experience. Below is the list of mandatory and recommended parameters, including their descriptions and status (required or recommended), for both Onsite and Offsite Retail Media. *** # Required Parameters
|
Product Category |
Example Sizes |
|---|---|
|
Men's T-Shirt |
S, M, L, XL, XXL |
|
Women's Dress |
2, 4, 6, 8, 10 |
|
Shoes (US) |
7, 7.5, 8, 8.5, 9 |
|
Kids Apparel |
2T, 3T, 4T, 5T |
|
Accessories |
One Size, Adjustable |
|
Furniture |
Small, Medium, Large, Queen, King |
|
Product Example |
Color Description |
|---|---|
|
Nike Air Max (Black/White) |
Black/White |
|
Levi's 501 Jeans – Indigo Rinse |
Indigo |
|
Patagonia Down Jacket – Forge Grey |
Grey |
|
Apple Watch Band – Midnight Blue |
Midnight Blue |
|
Floral Summer Dress – Red/Pink Combo |
Red/Pink |
## What's next * [Product feed examples](/retailer-integration/docs/product-feed-examples) * [Lookup files](/retailer-integration/docs/lookup-files) # Product Importer API Guide Source: https://developers.criteo.com/retailer-integration/docs/product-importer-guide ## Overview
# Product Feed Upload Guide Source: https://developers.criteo.com/retailer-integration/docs/product-upload-guide
## What's next * [Product feed parameters](/retailer-integration/docs/dataset-parameters) * [Product feed examples](/retailer-integration/docs/product-feed-examples) * [Lookup files](/retailer-integration/docs/lookup-files) # Ad Request Best Practices Source: https://developers.criteo.com/retailer-integration/docs/requesting-ads-best-practices ## Use of Filters Retailers can enhance the user experience by **integrating filters in Ad requests** when a user selects a filter onsite. Any time a user selects a filter, **a new API call should be made to Criteo including that filter**.
## What's next * [Formats overview](/retailer-integration/docs/format-overview) # Glossary Source: https://developers.criteo.com/retailer-integration/docs/rm-glossary
## What's next * [Introduction](/retailer-integration/docs/introduction-1) * [Product feed upload guide](/retailer-integration/docs/product-upload-guide) * [Product Importer API guide](/retailer-integration/docs/product-importer-guide) # Search Bar Dropdown Source: https://developers.criteo.com/retailer-integration/docs/search-bar-dropdown # Definition A Search bar dropdown **shows relevant products as the user types their keyword**. A new call should be made each time the predicted keyword changes. *** # Parameters ## `event-type` **Value**: `viewSearchBar` **Description**: Indicates to the API that this is a search bar dropdown event. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return (if any) for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewSearchBar_API_desktop`, `viewSearchBar_API_mobile`, `viewSearchBar_API_android`, `viewSearchBar_API_iOS`. * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewSearchBarApiDesktop`, `viewSearchBarApiMobile`, `viewSearchBarApiAios`, `viewSearchBarApiAa`. **Required**: Yes *** ## `keywords` **Description**: The search query entered by the user. If possible, send the final predicted keyword being matched for the organic results. For example, if by typing "app" the keyword being matched is `app store`, send `app store` in the API call. If the user then types "appl" and the predicted keyword changes to `apple`, make another call with `apple` in the API call. All keywords should be URL encoded. **Examples**: * `black%20laptops` * `black+laptops` **Required**: Yes *** ## `page-uid` **Description**: This value is returned within the response of the **initial call made on page load**. By storing this value and including it in subsequent `viewSearchBar` event calls, Criteo is able to link the events to the initial ad request. **Example**: `545d9a70-f096-4568-b4b9-8f2f32a452d4` **Required**: Yes *** # Sample Calls
## What's next * [AI assistant](/retailer-integration/docs/ai-assistant) * [Category pages](/retailer-integration/docs/category-page) * [Category flyout](/retailer-integration/docs/category-flyout) * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Search Pages Source: https://developers.criteo.com/retailer-integration/docs/search-page # Definition A search page is a **listing page showing the results of a user's inputted keyword**. Search result pages are divided into two types: * **Search result**: A search page that displays a product grid. * **Null search result**: A search page with no results and no corresponding product grid. *** # Parameters ## `event-type` **Value**: `viewSearchResult` **Description**: Indicates to the API that this is a search result request. **Required**: Yes *** ## `page-id` **Description**: An identifier that tells Criteo which placements to return for the ad request. Placements are instantiated by your Technical Account Manager depending on your desired ad configuration. Below are the standard page-ids for this page type: * **In Americas**: Typically follows the structure `[event-type]_API_[environment]`, e.g., `viewSearchResult_API_desktop`, `viewNullSearchResult_API_iOS` * **In EMEA**: Typically follows the structure `[event-type]Api[environment]`, e.g., `viewSearchResultApiMobile`, `viewNullSearchResultApiAndroid` **Required**: Yes *** ## `keywords` **Description**: The search query entered by the user. Should be URL encoded. **Examples**: * `black%20laptops` * `black-laptops` **Required**: Yes *** ## `item` **Description**: The list of SKUs that are organically shown on the page in the grid or list. Must match the parameter `id` in the feed (See details [here](/retailer-integration/docs/product-feed-parameters#id)). Multiple items should be separated by a pipe `|` or `%7C` (URL encoded). Used for reporting and for organic deduplication, if enabled. **Examples**: * `123|456|789` * `123%7C456%7C789` **Required**: Recommended, but not required *** ## `parent-item` **Description**: Only use this if parent SKUs are being passed. Must match the parameter `item_group_id` in the feed (See details [here](/retailer-integration/docs/product-feed-parameters#item_group_id)). Multiple parent items should be separated by a pipe `|` or `%7C` (URL encoded). For SKUs that do not have parent SKUs, `NULL` should be sent instead. Used for reporting and for organic deduplication, if enabled. **Examples**: * `12345P|NULL|456789P` * `12345P%7CNULL%7C456789P` **Required**: Recommended if the eCommerce platform uses parent items *** ## `list-size` **Description**: The total number of organic items on the page. Preferably, it should match the number of item IDs sent in the `item` parameter. **Required**: Recommended *** ## `page-number` **Description**: Represents the page number for either paginated results or scroll fold if products are loaded dynamically. This parameter can be used for result deduplication, by limiting the number of products shown on each page. Please note that a valid `page-number` starts at 1 and not 0. **Example**: `3` **Required**: Recommended *** ## `filters` **Description**: Corresponds to the filters applied by the shopper on the results. See the filter section for details on how to use this parameter. **Examples**: * `(price,le,100)` * `(color,eq,blue)` **Required**: Recommended. If not used, the ads will not follow the selected filters and might result in a poor user experience. *** # Sample Calls
## What's next * [Search bar dropdown](/retailer-integration/docs/search-bar-dropdown) * [AI assistant](/retailer-integration/docs/ai-assistant) * [Category pages](/retailer-integration/docs/category-page) * [Category flyout](/retailer-integration/docs/category-flyout) * [Product details page](/retailer-integration/docs/product-details-page) * [Favorites page](/retailer-integration/docs/favorites-page) * [Basket page](/retailer-integration/docs/cart-page) * [Order confirmation page](/retailer-integration/docs/order-confirmation-page) * [Organic add-to-cart events](/retailer-integration/docs/organic-add-to-cart-events) * [Filters](/retailer-integration/docs/filtering) # Seller Catalog Integration Source: https://developers.criteo.com/retailer-integration/docs/seller-catalog-integration ## Introduction This guide walks you through the steps required to configure your catalog to support seller offers, including SKU ID structure, Cross Seller Product IDs (CSPID), and Buy Box Winner (BBW) updates.
## What's next * [API parameters](/retailer-integration/docs/api-parameters-1) # Retailer Integration Changelog Source: https://developers.criteo.com/retailer-integration/changelog/changelog Release notes and announcements for the Criteo Retailer Integration documentation.
## What's next * [Introduction to Beacons](/retailer-integration/docs/introduction-to-beacons) * [Beacon Types](/retailer-integration/docs/beacon-types) * [Legacy & Universal beacons](/retailer-integration/docs/legacy-universal-beacons) * [BeaconSDK](/retailer-integration/docs/beacon-sdk) * [Server-Side Beacons](/retailer-integration/docs/server-side-beacons) * [Ad Tracking Best Practices](/retailer-integration/docs/ad-tracking-best-practices) # Ad Tracking Best Practices Source: https://developers.criteo.com/retailer-integration/docs/ad-tracking-best-practices ## Double Tracking Metrics * Ensuring data accuracy & performance insights: Since the retailer is responsible for firing all `load`, `view`, and `click` events to Criteo, they should also track these metrics internally.
# API calls Source: https://developers.criteo.com/retailer-integration/docs/api-calls-checklist # Introduction This page presents a breakdown of all the parameters needed for the API calls by common parameters (that can be used on all page calls) as well as by page type. *** ## Common parameters
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
Your Criteo Account ID, will be provided by your technical contact
Ex:
|
Yes |
|
|
|
Unauthenticated User ID, consistent across sessions
Ex:
|
Yes |
|
|
|
After logging in, whether there is a unique user ID Can also log in with a different device or log-in with the same account on another browser/incognito.
Ex:
|
Yes |
|
|
|
Hash value of the user email address SHA256
Ex:
|
Only if discussed with your Criteo team |
|
|
|
To be used when the log of this call shouldn't be counted as a real page view. (used for our cached API response scenario)
Ex:
Can be used on preprod accounts. |
Only if discussed with your Criteo team |
|
|
|
A parameter to be used to return the specific products that are set in the call, only for sponsored products. To be used with the cached API response scenario or to use the recommendation engine. |
Only if discussed with your Criteo team |
|
|
|
The region IDs that are sent are accurate to the regions IDs that are shared in the daily feed. If multiple region IDs are to be sent, then they need to be separated by the pipe symbol.
Ex:
|
Only if discussed with your Criteo team |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
IDs of the organic products visible. These IDs need to match the product IDs provided in the feed. They will be used for deduplication in the ad response
Ex:
|
Yes |
|
|
|
The parent item ID of the organics products on the page, if the product has a parent ID.
Ex:
This should only be used if parent/child SKUs have been set up. |
Only if discussed with your Criteo team |
|
|
|
The current page-number.
Ex:
|
Recommended |
|
|
|
The category path of the current category, either numerical or alphanumerical. The path provided in the tag needs to match "product\_type\_key" from the feed
Ex:
|
Yes |
|
|
|
Used to restrict the response to products which have a certain attribute with the exact value in the Feed
Ex:
|
Only if discussed with your Criteo team |
|
|
|
The total number of organic products that show on the page.
Ex:
|
Recommended |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
IDs of the organic products visible. These IDs need to match the product IDs provided in the feed. They will be used for deduplication in the ad response
Ex:
|
Yes |
|
|
|
The parent item ID of the organics products on the page, if the product has a parent ID.
Ex:
This should only be used if parent/child SKUs have been set up. |
Only if discussed with your Criteo team |
|
|
|
The current page-number.
Ex:
|
Recommended |
|
|
|
The keyword which was entered by the user
Ex:
|
Yes |
|
|
|
Used to restrict the response to products which have a certain attribute with the exact value in the Feed
Ex:
|
Only if discussed with your Criteo team |
|
|
|
The total number of organic products that show on the page.
Ex:
|
Recommended |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
Item of the currently visited product. This ID needs to match with the ID provided in the feed
Ex:
|
Yes |
|
|
|
Parent Item of the currently visited product. This ID needs to match with the ID provided in the feed. We can only use this to update all the variants (child products)
Ex:
|
Only if discussed with your Criteo team |
|
|
|
The current price of the product. This price will be used to update the product price on criteo's side in real time
Ex:
|
Yes |
|
|
|
Current non-discounted price / MSRP of the product.
Ex:
|
Recommended |
|
|
|
The current availability of the product, 1 for "in-stock", 0 for "out of stock". This value will be used to update the in-stock value of the product on Criteo's side in real time
Ex:
|
Yes |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
For the
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
The ID of the product that was added to the basket, the SKU that has to match the ID provided in the feed.
Ex:
|
Yes |
|
|
|
Parent Item of the products currently in the users' basket. This ID needs to match with the ID provided in the feed. We can only use this to update all the variants (child products)
Ex:
|
Only if discussed with your Criteo team |
|
|
|
Array of products in the basket single unit price
Ex:
|
Yes |
|
|
|
Array of quantity of each product in the basket
Ex:
|
Yes |
|
|
|
Unique ID present at the bottom of the API call of the current page.
Ex:
|
Yes |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
Array of products in the basket, including SKU that has to match the ID provided in the feed.
Ex:
|
Yes |
|
|
|
Parent Item of the products currently in the users' basket. This ID needs to match with the ID provided in the feed. We can only use this to update all the variants (child products)
Ex:
|
Only if discussed with your Criteo team |
|
|
|
Array of products in the basket single unit price
Ex:
|
Yes |
|
|
|
Array of products in the basket overall quantity of the item
Ex:
|
Yes |
|
Title |
Name |
To Check |
Mandatory |
|---|---|---|---|
|
|
|
The page ID should follow the format of:
EMEA:
AMER:
Ex:
|
Yes |
|
|
|
We are using the
|
Yes |
|
|
|
Unique order / transaction ID
Ex:
|
Yes |
|
|
|
Array of products bought by the user, including ID, single unit price and overall quantity of the item. The ID has to match the ID provided in the feed.
Ex:
|
Yes |
|
|
|
Parent Item of the currently visited product. This ID needs to match with the ID provided in the feed. We can only use this to update all the variants (child products)
Ex:
|
Only if discussed with your Criteo team |
|
|
|
Array of products in the basket single unit price
Ex:
|
Yes |
|
|
|
Array of products in the basket overall quantity of the item
Ex:
|
Yes |
|
|
|
The local currency of the retailer should be added here
Ex:
|
This should only be used if discussed with your Criteo team |
* **`products_order`**: some real time product substitutions are allowed based on availability of SKUs:
* **`products`**: an array of product IDs. The order of products returned by Criteo should match the order of SKUs displayed on the site, unless a SKU is unavailable or out of stock.
* **`isMandatory`**: If true, the overall ad unit should **not**be displayed if this product is not available. If false, the ad can be shown, but the button/product tile should be removed from the unit. *** ### `Rendering` * **`rendering`**: format-specific properties to use when rendering the ad, including image assets, colors, and custom labels.
|
Field |
Description |
|---|---|
|
|
Do not use this field. It is reserved for Criteo purposes only. All video-related information, assets and tracking must be used from the VAST XML only. |
|
|
Do not use these fields.
It is reserved for Criteo purposes only. The optional redirection link to a landing page if the user clicks on the video player is available in the VAST definition (cf.
|
|
|
Text to display in an alt\_text div attribute for WCAG compliancy purposes. |
|
|
Free text field to display a legal message upon user hover. This field is optional for the advertiser to complete. |
|
|
Do not use these fields. It is reserved for Criteo purposes only. |
## What's next * [Video player specifications](/retailer-integration/docs/video-player-specifications) * [Tracking ad-related activity](/retailer-integration/docs/tracking-ad-related-activity) * [Criteo-Owned Video Player Integration](/retailer-integration/docs/criteo-owned-video-player-integration) # BeaconSDK Source: https://developers.criteo.com/retailer-integration/docs/beacon-sdk This guide details the process for automatic beacon tracking on web using our Criteo's BeaconSDK. # Introduction BeaconSDK is Criteo’s lightweight external JavaScript library that automates beacon tracking on web. It handles the entire beacon lifecycle (load, view, and click) so you don’t have to build or maintain a custom tracking logic. The result is faster integrations, cleaner data, and consistent measurement across all placements and products.
## What's next * [Introduction to Beacons](/retailer-integration/docs/introduction-to-beacons) * [Beacon Types](/retailer-integration/docs/beacon-types) * [Legacy & Universal Beacons](/retailer-integration/docs/legacy-universal-beacons) * [Server-Side Beacons](/retailer-integration/docs/server-side-beacons) * [Ad Tracking Best Practices](/retailer-integration/docs/ad-tracking-best-practices) # Beacon Types Source: https://developers.criteo.com/retailer-integration/docs/beacon-types This page breaks down the different types and levels of Criteo beacons Here is an example of an API response returning a Commerce Display ad unit: ```json expandable theme={null} { "status": "OK", "onLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=sdfn829dJSHcuis_fSDJKF78wHZ_SVwv_cfy0nSfkSFHFffYs65nds6nvdshf3Rs5_fdFRGzlWsjGIawBFDQswMswBhq7yK14eKmK4cNZAPnq0etO07G-53EGqVKmlCUIqFt_HLAE2h0KJZSn_d4ozkI900RUgu-L-97OWqk_mrnkpvN-eFxXG8CM19U4n4S1QChcpDyMg1_qrbjK8lvNsCyAYioy8D-YBwHbXlMDcljf1B7Vx9-pyh4m9CMuWDuVLOcjtZ3fJ3ls9_j1bD1eEG41oHOq4dO6DS3HuTaLRTPVDHkFP8ck_WxJYyo7OSO98AB98AqM1Ra_WG9WTeJ8xTVLxBu5hF9yVdBjnZbXAyhF88_Ktm0B74rTMkB7qkHBLRvsaZh2UTESdH7nD_wP2wnjVO-McJ0mDQUFiBUzPOljik0OJA61fsKSTES4AvHr4VEVdYMZSA09obJWFwbCUMweFhLdURgHrtHOXqSXbqXTZBDx1jGocZHEwqD5nsJMdqebDg0_CEg8HBqoCZLfQI6Yfw&ev=4", //Page-level load/impression beacon "placements": [ { "viewHome_API_desktop-Flagship": [ { "format": "FS", "products": [ { "ProductId": "16823", "ParentSKU": "16823", "OnLoadBeacon": "", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=s4MUgb0p2qiOW6OXiDQ9tl3s-sHHnt2WXqEoCFO8R3FKGSf3dJWtjvWJEO7oKG19T75RS1_tbsMbbQCZmgXk29dnbhUX1BJOFSzGWXdpHb3Cvj_qbatHmoLwpWIpki6xbLOPpdjwesx9gx3WSrajV0KwNtGRCWlILLZMBTSBiBzXrbnR0pmTkyJwdxHN-xR70VuGcOCWXcoDxFcgXs2x7mjF7Bwo8Rv7ncoIDJuh1rSGX_eUE_2fu5s1COjtAtjOF9IpByRHiUzfTBkOoLLNMlCo6CrLo3cksFuFvJ93xiMx3oGp2g-WPejLjeIlBuYP_3Ps6tkScZNxUz1I8YwSqgeLWUmvyV0DnAKZH-JcXGhn7Rd2R2FClEFuXoBYtrFj1LTlhf_q9_KMBgQ3NvH4uQ&ev=4", //Product-level view beacon "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=IZWg4EkEK2twk5A7D_FAZVTkQxrW_ZFxNplIQ6Bmm5D_XAvAlG6HlVf-rJGM0cc20c_yhL-uslQy9FlYrfiD-U7iN0q9ldQKcxiKGu36ld2oFSR3uS87hWKeOz27ZMUChe8wack-2c0_zcRnyKhzmD-T0E-87RgHDBMNewjwnbNQLbjRpI7Ho6ox7Hsjp4Pb389yx3uDTNJ4rX8P_K3IhmgVpqCUH_h7DmntcCIATWySeiJECSBIizJ_MUSyzDdb88Fbj0frlauQ5J6vjhO32igX_HmfCtolAOuKVTQMJK5z4C_ZWlEDtXNR2rYdC6nCMBYh7gcbR-XQJZBsn3K9slOS67lQJ5Y8LsCtuAyxqPkonbjuF7vKMQdqXI-ukbuscGoVFz030rvZbabkjs6AQQ&ev=4", //Product-level click beacon "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=84B7sn1OYECasc1VjXL4JFN1RFip8yb42Dt90z7yfYSFQ5cKQhvDw9-KEFdvsSrmaZbxrW24g1xK24fQDXRm5vqlRpQ84UbJ1Voua3k3K0DhhlpLvUZf8MCcY7G8R4J-8l1Thhy9vAgaQ9Reh2l_pKtn0G9yobBXdzdG5b_ZM6CuF7a4c2fwvZoo-oFtZisOQq2yw2D0O0leQYlofB74IsGCoo_x2vpUL5xlPtA4GvBK9LURx9waJZ9bSC1VScEd5yJDPGw0cAGHlZJ67IwybQTi36v23TGej0cEimkaEAZeE6HsR4a-w1ALeVFzNl_uaHwDYx9pqhG3vIHzwbBG8nbBy8gQTI7fLA6NZBZMmLchZBW2ZBv8PzkkndgxAP5_RWZNYRp8HSdqHnL6vM9j0A&ev=4", //Product-level click beacon (for add-to-cart-click) "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=p-qo5UOTqS4wf7Xr1RzsVOdHHhtWkTjtnyS7LFTEVS7gzTgX1yp4AkZzq4ABrxS_-n3CvbV7MEflqu8jW7lHyftktBXZj4736aIGbBvQQK8zss9Pcvb44_tuPWaUO6K6XxEGo72DhlU9SVxL5ggENsS5x8RcRVxL20B4na9cJrbZ_PGXyVyBLrdmmkdn29ToWhDWpdSxA0op5nk8c9UU0IVgpWC3ZOepgB2toTH9AyIZi1zcwxEutGpQ2ptLrS0hVSyVxPWIWFsLr6F49fWje0rB-klFEjPjPj6D9zMgdT3I89UQL8Jaim0q_C_vqgOO3FG5ecwigCvS-j3kDWEThDlOVYg9QTUlupSrtP9T3K1Zdl0I4RQeP2s5oF9L7GdvX73_K7Zeb_5DZqCOEpfFqw&ev=4" //Product-level click beacon (for add-to-wishlist click) }, { "ProductId": "19494", "ParentSKU": "19494", "OnLoadBeacon": "", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=y5-OVUh7SAs63ua-tXWrE-hKBle8TbRjb7ITYuhBBqSTmkBxrXnxnPmHXVAby_gDc5aCqM3rF66tJY5CzFAxdIPOU9hujzb22R6nC5s4BNOmZHySBOwv-Omfsj02E1_vyAmov2TmeZofRM_ixmc7Gb-9vnD-Nya8Jus1kOLcoMF_wSDrMSlHxOpm6-fnqVEpEgnPkW4gPokouZC-bL-UPKxQM8SxsNCeaJimBcu2Pund-1SkkkK95O-qq4kboHjwnfmIijOHtFe0Xfsjsqscxy2Akz860toeZn-KISs8YBrOJBUdm82c1bHrZ5LB7NPR1iDOtzwe2ef_at96hCHoyrh-4e0v2o2jGqaoUG-E_ITG_Z2j01xs00dMqyKoPn4VEp7AzvO_ogH3sosgrBwnBg&ev=4", "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=GR3fsa56mrEr8_rFee3jXYX46r69EHtPMAhvltFZM3TrjpzouRWR4ZOgWCegEKcH0C-wfg7JBqJEpDoxsTpPhvlm7stXwjqYgSItt95pkeuie8YEqLgGJGBeY-ljC8sO4JKbMjtY3eMrR8Esw7zM1paZGzYUpple4AAfTdbT1L03tLKgfz4dFcGO9_Q91smQvneqseV8qmUjcbkroMcC8-0NNPWRzPT6QnucQlsBZuiFgDvTrpUrvbwgS41hh8KW1anp5FFqFHyL2jSM0lH0lHahdo4hxxJyWOoIceGSNfGE0-nwMHmvmqeqszbmgrMfz_C5fpSsa_M8fOVBg-7g3iZcGTFDZ33WgTQnqt7VCfV1xRwUVvBSrg3klW0wgeNDrSuEJzCtlkv8pV3pupD2-Q&ev=4", "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=Bvr2njkxIMlNUUbyH6ubRMJqIgw6p7mQjYr7z3tr3W1elo-OkTojl7W6yJUkRb14EiWFtJG8Jo8OeUhy-ArRym5HceeaM-vRFpFOv7weYyYe565sLG5bQBdZhXHJASWBVXobBZ4PCxniZVp-JNpCB2aU-btujaeNfeayNwtHpV24p-SkxauLgOXRy_FIlSjmZkJkGIRukzRMwxWKh55W43LxVr-2uVtOqq6Tg8QLJOneRks0noLnlOST-l2hHMJxJqK-AModUnuY5T8sn3s6x6epRtRMfDoi5MOkJooju16qurFbT6qyGNFSb_hMf82IfdA86pjRpeWJ9DBC3UAZF_bhgTZVjnX1qwHVF_GR3i-kRbNHt30BvZFMJwjO09BqMVx8bZKZaOR5iHMbHIkogA&ev=4", "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=jMoh1dvUxY5LlNEdfXlGZmXRCxi5QSVhFfgptMG1pGyeAYbZ2jvsYVhDqTrFvbLIM7kHi2y1RHXzmNPfHvZifBQpW9sh26BRsuVLdljLruxfxZT_Wtyi4D1KcCA3A09vz4mCIm1MuzHlXTPN-y7oTJqPajjzkeSJSDQFbX-hYEANVbIKhjPET7udRb8R34MtYZQFuqgOuWpCXqPh0JdQSDX9DuLewmI3ZfznR9IeWAwCPMZjiVAZ8KPR6Gy-SsaoLumggq-ikAj3svtK419b47u2ukbW_5S4pZeaq8glbE6nNLpUQdt5k9Drp9echMVY2Y6YkYlvHipFlLqdmrEjKYQ6_oEVVIooxSUt97nUfeQE653nmSN9RlHDfCw8AaaEjaiINAd82jyoMbOD9BezBg&ev=4" }, { "ProductId": "15742", "ParentSKU": "15742", "OnLoadBeacon": "", "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=nA2BvAMRGhTnq4v2AWuk3BNlPZna1pHKObORJAkN7oW6vUC_e70WtzBFKV40CyiVAX_Dl8i38Bouu9GWQambqmxwZDQgcrWgHE7AOTGMr229QTu9ZpkAAJiuvLLgLp1BdieXDoQUH7Mr5tj_JNcD8ufIW3V6qBEXsg_FB8rzmTbwaQ8Pzx5E0ukEYUUqVHBZmqS7jZqo0jfmihYR9X6U0_ayKed1mps5qHH8k9MeF6T_bMCZt7aN9ipLLPxRPOmgt-852ZDiaixUr-f0qFxFs9XobID5y5mO7TJX2dKjQjVyTeoxSfXkjdQN8JX5SYwuDtl_8k4qExzr6zZ1oL5acfimqVPrixtdBWP3DKILdDwumWp31ZdPxTq9JPbNUyE919WZLeoblsCk8Kcp5t2eYw&ev=4", "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=NhGtK-T_dijg2M8c4LyLStkPbVv7l1C525iJEsTLvLaooegslXLpxbwPoIeWSfy9U2Re1Zd-l_K8UjsfBvHe6aizQ7UQsZ562DLuXGFebWcMflPhmLZ3Fy_LIH1plFbg9KmOYHhCDyeioUvBdZhqZSOeYper5LOOKP57Ld4QMh-fCtWzv0ScZpM8oWMDJMVLTF1SuT2bLFs9ZRfmNCNnu6obAecVxvv31Iod7010gme-pnvA4gImYh1rCIVZ95ISx0FmjVVw-Im5fVbjgKF2p4m8q-DPM8cpS_LvS6stnoOPi2DLDb-TM07sS4GyzB0KGIfKkMeaVBOSNvTYY4JeSJ6qGASrd2osYVFgW3l1jfB7oqkyPpRjkTCh-V4gc7xjPD01sNmqL9BOM9-jWrOO3Q&ev=4", "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=65vo05e5FJF5RdRTgEI508JGOmZzDY2210JZqqjV1L20AgkC6dXSadUc6VrIOpxvs0_kzeBSNfJgwKlRoiqbuBGWKIAFnfLm3d5vSzefbV_ZSddTOsb-ZX6yNf8oxxo2EIur4BM_nu8Mu_eh4UsLK1Mq1AeEmvQ6ZJEDf9Yz4l2ouG2JrQf2NW-lyO5SI9vyKuA3SNx2S2Sf_pRP4cbGuGpfRQXxHLV_K1VXoMpJW9reKlzQv8_u7A6XdEgyX3GwVM4AITNMA6PbNsKKQdTER3ywdDyydPiAdA7jg9UOMP098RYzYi43XZPpLbLyOxvaqdKVLYyq8UBME6E6Wr7eC267SQiJn8r-jqffU6iUfH4WgUMRtOQwfbx0hGH4yJJu8y0v5JAxwxAld5VwEfP30Q&ev=4", "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=RbrsRpZFm59CHAoMg0iamPzWIAOB-61izO9f1XjyUSq5GuyvZLEhy1sc7r9qWO1WWT-eZIgPp46p6J56FEodBIbdnKL844tC0f-i3pKSz26rsL1kIepzVOtAMgm_1UCCc1q2iFXeRSIPmgS1IejfR6ToEtRgylUhxjJWBEAzA1wOtSFAbOX6j3YbtqjLMRsaxgKdvSPC2h_agZ8v5JoC5zpL70crF5JhLdojd42VCzv9STkVcISbDvCovbveL92KA_GfB-NDt4mIN8_NHHZeM2_szqLeVdbv82A759STYaSZD0AzA4OFcYnGtBYplYgxK8pqgJMYPZ9yob_las_A9AHE-AUkJYKoRZDvlETUHon0p8TlYQXkpDqnVP_maU6BIpUMmmfe5NJzdwk9pSrPJQ&ev=4" } ], "products_order": [ { "products": [ "16823" ], "isMandatory": false }, { "products": [ "19494" ], "isMandatory": false }, { "products": [ "15742" ], "isMandatory": false } ], "rendering": { "desktop_background_image": "//retailmedia-static.azureedge.net/creativeassets-live/d6bfdeefc36e382e53befaeed8d1dc53f07110131a75b275c48fdbf279f4e853.jpg", "desktop_background_image_alt_text": "", "mobile_background_image": "//retailmedia-static.azureedge.net/creativeassets-live/71a4499cd0f16fe4f1ecd475b7b90e63188f45b212e1cce3bd1aae5a148e34d9.jpg", "mobile_background_image_alt_text": "", "optional_footer_type": "file", "optional_footer_redirect_url": "www.criteo.com", "optional_footer_redirect_target": "_blank", "optional_footer_redirect_url_app": "www.criteo.com", "optional_footer_media_file": "//retailmedia-static.azureedge.net/creativeassets-live/4ba277a9762360ac4ca6f933d522da5bfb7a7937c3491e3887291e994e512005.pdf", "border_color": "#CCCCCC" }, "OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=kwp2GQrVizyjE_f5R4AKDxHZ_SVwv_cfy0nnuxGkZI4uv3YzfiEKFcBm3Rs5_fdFRGzlWsjGIawBFDQDyMg1_qrbjK8lvNsCyAYioy8D-YBwHbXlMDcljf1B7Vx9-pyh4m9CMuWDuVLOcjtZ3fJ3ls9_j1bD1eEG41oHOq4dO6DS3HuTaLRTPVDHkFP8ck_WxJYyo7OSO98AB98AqM1Ra_WG9WTeJ8xTVLxBu5hF9yVdBjnZbXAyhF88_Ktm0B74rTMkB7qkHBLRvsaZh2UTESdH7nD_wP2wnjVO-McJ0mDQUFiBUzPOljik0OJA97OWqk_mrnkpvN-eFxXG8CM19U4n4S1QChcpDyMg1_qrbjK8lvNsCyAYioy8D-YBwHbXlMDcljf1B7Vx9-pyh4m9CMuWDuVLOcjtZ3fJ3ls9_j1bD1eEG41oHOq4dO6DS3HuTaLRTPVDHkFP61fsKSTES4AvHr4VEVdYMZSA09obJWFwbCUMweFhLdURgHrtHOXqSXbqXTZBDx1jGocZHEwqD5nsJMdqebDg0_CEg8HBqoCZLfQI6Yfw&ev=4", //Placement-level load/impression beacon "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=qrL1X0gCc0_99xluW-KXwEkCluMc7SLNbBgcDjm5todnq1SSYEcQOpthqyD69N3LbepzaFyoER1z3e7K0Y0Uv7c1fXuvlYMEkdn4Q-dx7wjkFHO_DsQwNSkSJTCk_6DKNjyksXYnzyKmuEP2AUuhfFeMPSfdtR_ogYx3YIxI4lej2XBnHXw7CH-6aS0UvfPItwL2CoTCwKmQIkQyRmp6PKCPe9di9n1YmlaQJ_o_y6MMwOC89kH6LYgNtWlIzkEa5NBzoAI41pgLJ5V1E4zqh6TKbWkQnHuEZWZE6HWtuxF7zj4zFfKXsWtOh8uGKiy-PkWbVS6n3ziq-x8Y6Z6bhbCs2DVu61eIsVLi9N-7lBwJvZRyk72tRHoSLQefIZ4teQsey0f8LoBixDIDvDFLMqtNT6UtF0kAdvVf1sGBnIGdYOskJmBpun_-5AxQ7JYYEKY8UgCuHRzuStz5kYAj6Q&ev=4", //Placement-level view beacon "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=SufwIvPHzAmyrws2Pgfyn0bOJ6OnniYbQfms_juqg1zhFOP8_X3Xpm1lZJC6O88f4c-jZg7RWVr4cYTOtb2-bZFwabzexJlZTOft3sHibcR0uMRdSzGrPpL0bl9zg6nH0zEo0BP_hVrLTgI8jNesN9RTeuEhSWdnKOcuO-p-rVwzyxmWlh-OmeQ_di2GrQsWIa8SOcnIiJnhTtDerJp4lYF3DHqA08xh0WqQO3y431Y0cAgYSFjQX-GCA57zd36gJ1C_-T2TlDtiaH0LA1vVJplIa6c3OgbDUJuJlSfW3947jn2gRHQMoDDxWyuTKR1A3QBKpSlxF9hpqc1FA6n_8Wk7_DOr001RLLVrnjSOmWPKLqkrFiu_BN9RR8rymj7bvV1wD2vXjrBY_hI8V-LiSQ&ev=4", //Placement-level click beacon (for clicks on the creative asset) "OnFileClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=sloVjDHD68JAycBoAJGWQyFIP0DqMYoAFJSP31JQMX-u2zibhPNIgYJyzM8jtfZSVWvTguYgX_L1liSpZKPDs5IFswQ65p8x6fY7r4SqOXke00gRuROKj9aEPXRTHLYyKUHX8giA0ensbt3KM-v4qMvJZoOKVBv2_27zEAhrPt4Zz6V0Y4kRTqJRaXXvSY5IyDvm2Vj-yGYY1-es5XNN_4K5rAXRYZZJn0n9nOwXe17MepTt5MXMqwrhot37Fcjbu5ww_HkGvFQMTTB3MCgEnEnMcyxYzHUV3nC0jJr5X42-8ny3baUynPFUnuKwSfzSGQL5_5PoOr5aIZnnzzbLCMbbzcn1AgLbSpsskwxnxdtt9-TZ1IUfCGQpWw4cB0Eb7Kax5CWgZbvYj1__gqZkJvwK47N_ebBHVS9XuqWNVVY&ev=4", //Placement-level click beacon (for clicks leading to file download) "OnBundleBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=6VUW1JJpcvC_2wJVOVs98zWwE58TE9NI_wWrdaOcnG6_HeWHFLog-1xP5F2v_zpXjCcrN6M7-PvXziHAb4BVZ5f7Tg7Rt-jhO7IkPhWVjrXE78djmHEhmgdUt9gFsFj4_4B_rYL5ZRa3QdlHns6BMntz39iElN0GnaTidmVd9aSWYM0Mw0DhT1DfvEisOsu4Dp87VFwJCRXqQB9J7tLlIEnf_m3KFvXdjImQ2x0yDUzAkVPwY_Ley-Vs3iSioioVl74xuW6rz9q2rDUCSC-B1TQETO3VmZd23H2BjrI5bF9IIShOiQG0SMtsYjHvFimInAJ9gmSbZLPi0QhopALOixXc79OJH7HbRv3DyF2ThXQX-A4F1dgXHjkk3IxY2fef803yG_Hdkbdw_UJ-rg__HQ&ev=4" //Placement-level click beacon (for clicks adding sets of products to basket) } ] } ], "page-uid": "954ae0b4-c0c4-4898-9c18-bdd154eb9353" } ``` Criteo beacons are categorized into three levels: * Page * Placement * Product Each level contains specific beacons designed for different tracking purposes. The following sections provide a detailed breakdown of each level, referencing the example API response outlined above. *** ## Page-level Beacons ### **`OnLoadBeacon`** * **Description:** This beacon is triggered automatically by the delivery service when the page loads. It only appears in the ad response when the parameter `nolog=1` is present in the API request, signifying it as a test call. ***Therefore, this beacon can be ignored.*** *** ## Placement-level Beacons Placement-level beacons are associated with the entire ad placement and not with individual products. These beacons are part of each "placement" object in the API response. ### **`OnLoadBeacon`** * **Description:** URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the unit begins to render. For sponsored products, the placement is considered "loaded" when at least one product begins to render. ### Handling Suppressed/Non-Rendered Products (applicable only for Universal Beacons) For SKUs that were not rendered, you **must** append additional parameters to the placement-level `onLoadBeacon` to avoid inaccurate impression and attribution counts. Here’s how to handle non-rendered products: * **Specify non-rendered SKUs (mandatory):** Append an **exclusion** parameter titled `&ex=` to the placement-level `onLoad` beacon with a pipe-separated list of the SKU IDs that did not get rendered for that placement. * **Add exclusion reasons (highly recommended):** Append a **status code** parameter titled `&st=` to the placement-level `onLoad` beacon with a pipe-separated list of status codes representing the reasons why each SKU in the exclusion list was suppressed. The full list of eligible status codes are outlined at the [bottom of this page](/retailer-integration/docs/beacon-types#non-rendered-product-status-codes) * **Note:** The number of SKUs in both the `&ex=` and `&st=` lists must be equal and correspond exactly with one another. If no status code is available, default to a value of `1` (generic catch-all status) * **Example:** `//b.us5.us.criteo.com/rm?rm_e=kwp2GQrVizyjE_....f5R4AKDxHZ_SVwv_cfy0nn&ex=SKU123|SKU456|SKU789&st=102|303|202` *** ### Handling Painted Slots Painted slot indices represent the position of each product as rendered in the UI within a placement. Providing slot indices enables accurate measurement and attribution at the slot level.
## What's next * [BeaconSDK](/retailer-integration/docs/beacon-sdk) * [Server-Side Beacons](/retailer-integration/docs/server-side-beacons) * [Ad Tracking best practices](/retailer-integration/docs/ad-tracking-best-practices) * [Legacy & Universal beacons](/retailer-integration/docs/legacy-universal-beacons) # Branded Header Source: https://developers.criteo.com/retailer-integration/docs/branded-header # Introduction Branded Header is a horizontal Commerce Display unit that consists of a Branding Zone and a Product Zone with a carousel of up to 5 SKUs.
*** ## Available options The branding zone can be clickable and contain the redirection (a CTA button is usually added to the background image to indicate it to the user. The button is part of the image, it's not a coded element). The user can click anywhere to be redirected. *** ### Redirection It can redirect to (only one is possible per format): * At the banner's click, it redirects to the link defined on the platform. It's possible to have it on `_Self_` and `_Blank_` redirection options (not applicable for App). *** ### PDF * At the banner's click, the PDF file opens like a redirection link. It's possible to have it on `_Self_` and `_Blank_` redirection options (not applicable for App). *** ### Other options
*** ## Implementation example ***
## What's next * [Flagship](/retailer-integration/docs/flagship) * [Showcase](/retailer-integration/docs/showcase) * [Interactive Header](/retailer-integration/docs/interactive-header) # Branded Header Source: https://developers.criteo.com/retailer-integration/docs/branded-header-1 Here is a breakdown of the requirements for your Branded Header placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all of the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both This beacon should be fired on every click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Differing product counts |
Ensure that the design for a single product matches the mock-ups and that all parts of the ad unit (SKUs, navigation arrows, navigation dots, buttons, etc.) ahere to the mock-ups when multiple products are returned. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Single product navigation |
Ads display without navigation arrows for both desktop and mobile and there are no "navigation dots" on the mobile carousel. |
Yes |
|
Multi-product navigation |
Ads display with navigation arrows for both desktop and mobile and there are "navigation dots" on the mobile carousel. |
Yes |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
#### Non-compliant Tile Dimension If the grid tiles do not match any of the above scenarios, other solutions can be determined and implemented as long as the Retailer safety zone and Brand safety zone is respected within the image. *** ### Alternative Mobile Layout This layout variant is optimized for mobile devices and single column product grids/lists. #### Background Image * The background image size is 1280 by 400 pixels or 1200 by 1000. * Please note that only one of these size will be used once chosen. * The image is fully responsive: * It scales proportionally based on the width of its parent container. * As the width decreases, the height decreases proportionally. * The image is never cropped.
### Color Mode The advertiser can choose between two preset color modes to ensure the best contrast between text options and the branding zone. Options appear while hovering over the Branding Zone. #### Light mode * Background color: `#FFFFFF` 80% * Icon color: `#6A6A6A` * Legal text color: `#000000` #### Dark mode * Background color: `6A6A6A` 80% * Icon color: `#FFFFFF` * Legal text color: `#FFFFFF`
## Styling Element styles, such as fonts and button corner radius, are determined by the retailer and the following details shows our default styles. However, button and text area dimensions must be adhered to so that the Retailer Safety Zone, Brand Safety Zone and component placeholders are respected. ## Call-to-Action (CTA) Button * **Max characters**: 25 * **Size:** 150 by 30 pixels * **Font:** Roboto Regular, 12 pixels * **Margin** * Grid layout: 5 pixels below button * Alternative Mobile Layout: 8 pixels between branding zone and button
## Legal Text and More Info **Desktop**
|
Detail |
Legal text |
More info |
|---|---|---|
|
Height |
40 pixels |
Dynamic, based on text length |
|
Padding |
5 pixels on both the left and right sides of the tile |
8 pixels, all around |
|
Font |
Roboto Regular, 12 pixels |
Roboto Regular, 12 pixels |
|
Max characters |
90 |
180 |
**Alternative Mobile Layout** * Legal and More info text will be displayed together * "See less" / "See more" option for expanded or contracted view of text * **Padding:** * 8 pixels, above and below * 10 pixels between CTA button and text * **Font:** same as Grid layout * **Max characters:** same as Grid layout * **Background:** Displayed over a colored layer (the layer color adapts based on color mode)
*** # Response Keys
|
|
Description / Parameter |
Description |
|---|---|---|
|
|
required:
maxBytes:
extensions:
width:
height:
safeZoneWidth:
|
Background image that can be used for desktop and mobile. The mobile image can be hidden through override if needed. |
|
|
required:
maxChars:
|
Text description of the desktop background image for ADA compliance. |
|
|
required:
maxBytes:
width:
height:
|
Background image of the mobile ad. |
|
|
required:
maxChars:
|
Text description of the mobile background image for ADA compliance. |
|
|
required:
|
URL users are redirected to upon clicking the background image or CTA button. |
|
|
required: true Options:
|
Determines if the redirect opens in the same tab (
|
|
|
required:
|
App-specific URL users are redirected to when clicking the CTA from an app environment. |
|
|
required:
maxChars:
|
Text displayed on the CTA button. |
|
|
default:
|
Text color of the CTA button. |
|
|
default:
|
Background color of the CTA button. |
|
|
maxChars:
|
Always-visible legal copy. Shown next to the CTA on desktop, and persistently on mobile and app. |
|
|
maxChars:
|
Supplemental legal information. Visible on hover on desktop ("i" icon), and persistently on mobile and app. |
|
|
default:
|
Sets visual mode for optimal readability. Light mode uses white text on dark backgrounds; dark mode uses dark text on light backgrounds. |
## What's next * [Commerce Display Grid Duet](/retailer-integration/docs/commerce-display-grid-duet) * [Commerce Display Spotlight](/retailer-integration/docs/commerce-display-spotlight) * [Commerce Display Grid Shelf](/retailer-integration/docs/commerce-display-grid-shelf) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) # Branding Display Spotlight Solo Source: https://developers.criteo.com/retailer-integration/docs/branding-display-spotlight-solo This guide provides the specifications and technical details for the Branding Display Spotlight Solo format rendering. # Introduction The **Branding Display Spotlight Solo** is a responsive horizontal display banner consisting of a still image and a redirect link.
### Mobile Specifications This layout is optimized for mobile devices and high density screens. **Background Image** * The background image size is 1280 by 400 pixels or 1200 x 1000 pixels. * Please note that only one of these size will be used once chosen. * The image is fully responsive: * It scales proportionally based on the width of its parent container. * As the width decreases, the height decreases proportionally. * The image is never cropped.
|
Detail |
Legal text |
More info |
|---|---|---|
|
Location |
below branding zone (right of CTA button if enabled) |
contained in interactive overlay |
|
Height |
Dynamic, based on text length |
Dynamic, based on text length |
|
Padding |
|
8 pixels, all around |
|
Font |
Roboto Regular, 12 pixels |
Roboto Regular, 12 pixels |
|
Max characters |
90 |
180 |
|
Background |
Displayed over a colored layer (the layer color adapts based on color mode) |
Same as legal text |
**Mobile layout** * Legal and More info text will be displayed together * "See less" / "See more" option for expanded or contracted view of text * Padding: 8 pixels, all sides * Font: Roboto Regular, 12 pixels * Max characters: same as Desktop and Tablet layout * Background: Displayed over a colored layer (the layer color adapts based on color mode)
|
Name (API key) |
Parameters |
Description |
|---|---|---|
|
|
required:
maxBytes:
extensions:
height:
safeZoneWidth:
safeZoneHeight:
|
Background image of desktop ad |
|
|
required:
maxChars:
|
Text description of the desktop background image for ADA compliance |
|
|
required:
maxBytes:
extensions:
width:
height:
|
Background image of mobile ad. Alternate size allowed:
|
|
|
required:
|
Text description of the mobile background image for ADA compliance |
|
|
required:
|
URL user is redirected to upon clicking on the CTA button |
|
|
required:
Options:
|
Defines whether redirection opens in the same tab or a new tab |
|
|
required:
|
App URL user is redirected to upon clicking CTA from an app environment |
|
|
required:
|
Text label of the CTA button |
|
|
default:
|
Text color of the CTA button |
|
|
default:
|
Background color of the CTA button |
|
|
maxChars:
|
(Desktop) Visible next to the CTA (Mobile & app) Always visible |
|
|
maxChars:
|
(Desktop) Shown on hover via “i” icon- (Mobile & app) Always visible |
|
|
default:
|
Determines the contrast mode for optimal legibility depending on image brightness |
## What's next * [Commerce Display Grid Duet](/retailer-integration/docs/commerce-display-grid-duet) * [Commerce Display Spotlight](/retailer-integration/docs/commerce-display-spotlight) * [Commerce Display Grid Shelf](/retailer-integration/docs/commerce-display-grid-shelf) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) # Branding Video Standout Source: https://developers.criteo.com/retailer-integration/docs/branding-video-standout Branding Video Standout is a format combining a branded video with a branded image and a CTA. # Overview The Branding Video Standout is a hybrid format that bridges awareness and commerce, a storytelling ad that still drives measurable action.
|
Key |
Description |
|---|---|
|
|
Image file.
Required:
Width:
Height:
Max size:
Extensions:
|
|
|
Alternative text for the branding image.
Required:
Max characters:
|
|
|
Background color for the full unit.
Required:
Default:
|
|
|
Border color for the full unit.
Required:
Default:
|
|
|
Main ad message.
Required:
Max characters:
|
|
|
Color of the messaging text.
Required:
Default:
|
|
|
Brand name displayed with “Sponsored by” tag.
Required:
Max characters:
|
|
|
Legal text add-on for the video.
Max
Desktop: visible on hover of the “i” icon; Mobile/App: always visible below the video. |
|
|
Only for web. Ignored if no ClickThrough is provided in the VAST.
Values:
|
|
|
Video alternative text for accessibility. |
|
|
Preset theme for UI elements. Values:
|
|
Key |
Description |
|---|---|
|
|
A URL to load a VAST XML that includes all information to render the video part (left side). |
|
OR |
* |
|
|
A VAST XML to provide a video player |
|
Attribute |
Specification |
|---|---|
|
File size |
300 MB |
|
Supported file types |
MP4 |
|
Video ratio |
16:9 |
|
Max duration |
30 seconds |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
90 characters, including spaces |
|
Attribute |
Specification |
|---|---|
|
File size |
300 KB |
|
Supported file types |
JPEG, PNG in 72 dpi. |
|
Dimension (W x H) |
1200x1200 |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
140 characters, including spaces |
|
Attribute |
Specification |
|---|---|
|
CTA Text |
25 characters, including spaces |
|
Redirection URL |
Choice on redirection target: On current page, on new tab |
## What's next * [Commerce Video Grid Duet](/retailer-integration/docs/commerce-video-grid-duet) # Butterfly Source: https://developers.criteo.com/retailer-integration/docs/butterfly # Introduction The Butterfly is an **in-grid Commerce Display unit combining branded assets with product tiles**.
|
Field |
Description |
|---|---|
|
|
URL of the background image file for desktop/tablet app |
|
|
Alternative text for desktop background image |
|
|
URL of the background image file for mobile |
|
|
Alternative text for mobile background image |
|
|
URL of the logo image file for mobile |
|
|
Alternative text for mobile logo image |
|
|
Hex code for the format's outline color |
|
|
Hex code for the background color of the branding zone |
|
|
Product button color |
|
|
Selected product button color |
|
|
Product button text color |
|
|
Selected button text color |
|
|
Option type. Can have the following values:
|
|
|
Option text (non-applicable for mobile version) |
|
|
Web URL that the user is redirected to |
|
|
App deeplink that the user is redirected to |
|
|
Redirection target. Can have the following values:
(only applicable for web) |
|
|
URL of media file |
|
|
Option text color |
|
|
Option background color |
|
Field |
Description |
|---|---|
|
|
The button text |
|
|
The product that should be rendered when the button is clicked. The array is contains the priority order of product rendering. If you are checking product availability in real time, you should render the first available product in the array, i.e., if the first product is not available, check the second one, then check the third, and so on. |
|
|
If
If
|
## What's next * [Branded Header](/retailer-integration/docs/branded-header) * [Interactive Header](/retailer-integration/docs/interactive-header) # Butterfly Source: https://developers.criteo.com/retailer-integration/docs/butterfly-1 Here is a breakdown of the requirements for your Butterfly placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all of the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both This beacon should be fired on every click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Product button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Product button text |
Ensure the name can fit on two lines and supports at least 20 characters of text |
Yes |
|
Redirection button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Redirection button text |
Ensure that the button text supports up to 20 characters in length. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Product navigation |
Ads display without navigation arrows for both desktop and mobile and there are no "navigation dots" on the mobile carousel. |
Yes |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
|
|
Description / Parameter |
Description |
|---|---|---|
|
|
required:
maxBytes:
extensions:
width:
height:
safeZoneWidth:
|
Background image that can be used for desktop and mobile. The mobile image can be hidden through override if needed. |
|
|
required:
maxChars:
|
Text description of the desktop background image, used for ADA compliance. |
|
|
required:
maxBytes:
extensions:
width:
height:
|
Background image of the mobile ad. |
|
|
required:
maxChars:
|
Text description of the mobile background image, used for ADA compliance. |
|
|
required:
|
The URL users are redirected to when they click the background image or CTA button. |
|
|
required:
Options:
|
Defines whether the link opens in the current tab (
|
|
|
required:
|
App-specific URL users are redirected to when they click the CTA button from an app environment. |
|
|
required:
maxChars:
|
The label text displayed on the CTA button. |
|
|
default:
|
The text color of the CTA button. |
|
|
default:
|
The background color of the CTA button. |
|
|
maxChars:
|
Legal text always visible on mobile and app, and next to the CTA on desktop. Typically used for trademarks, copyright, or disclaimers. |
|
|
maxChars:
|
Supplementary legal or disclosure text, shown on hover (“i” icon) on desktop, and always visible on mobile and app. |
|
|
default:
|
Determines whether the creative uses light or dark mode, optimized for different background hues. |
### Color Mode The advertiser can choose between two preset color modes to ensure the best contrast between text options and the branding zone. Options appear while hovering over the Branding Zone. #### Light mode * Background color: `#FFFFFF` 80% * Icon color: `#6A6A6A` * Legal text color: `#000000` #### Dark mode * Background color: `6A6A6A` 80% * Icon color: `#FFFFFF` * Legal text color: `#FFFFFF`
|
Detail |
Legal text |
More info |
|---|---|---|
|
Height |
40 pixels |
Dynamic, based on text length |
|
Padding |
5 pixels on both the left and right sides of the tile |
8 pixels, all around |
|
Font |
Roboto Regular, 12 pixels |
Roboto Regular, 12 pixels |
|
Max characters |
90 |
180 |
**Alternative Mobile Layout** * Legal and More info text will be displayed together * "See less" / "See more" option for expanded or contracted view of text * **Padding:** 8 pixels, all sides * **Font:** same as Grid layout * **Max characters:** same as Grid layout * **Background:** Displayed over a colored layer (the layer color adapts based on color mode)
## Layout and Borders * **Grid layout (desktop and mobile):** 1px border surrounds both the branding and product zones. * **Alternative Mobile Layout:** 2px border surrounds the full creative, including product listings. * **Padding:** 10 pixels of spacing around each product listing. ## Background Image * **Grid layout (desktop and mobile):** * The background image is centered and is cropped from all sides * Image size rendering is determined by grid-based scaling presets * **Alternative Mobile Layout:** * The background image has a fixed position and is never cropped * It scales proportionally to fit its container. ## Navigation and Slider Behavior * The design of navigation **dots or arrows are customizable** to match the retailer’s native UI * When the user releases the slide, the product with the **largest percentage of visibility** becomes the main displayed product ## Product Zone Behavior * Product information dynamically fits within the product zone * For Grid layouts (desktop and mobile), the tile height is determined by tallest product in the row. * For the Alternative Mobile Layout, the product zone **maintains a consistent height**, regardless of the width of the branded header ### Alternative Mobile Layout Product Visibility Logic * If only **one product** is present: * The product is **100% in view** * If the viewed product is **first or last in the list**: * The main product is **80% in view** * The adjacent (secondary) product is **20% in view** * If the viewed product is **in the middle of the list**: * The main product is **80% in view** * Each adjacent product is **10% in view**
## What's next * [Commerce Display Grid Duet](/retailer-integration/docs/commerce-display-grid-duet) * [Commerce Display Spotlight](/retailer-integration/docs/commerce-display-spotlight) * [Branding Display Grid Solo](/retailer-integration/docs/branding-display-grid-solo) * [Branding Display Spotlight Solo](/retailer-integration/docs/branding-display-spotlight-solo) # Commerce Video Grid Duet Source: https://developers.criteo.com/retailer-integration/docs/commerce-video-grid-duet Commerce Video Grid Duet is an in-grid format combining a video file with one or more product SKUs. # Overview The **Commerce Video Grid Duet** format combines a video file with one or more product SKUs. The image below showcases the desktop format at the top and the mobile format at the bottom.
|
Key |
Description |
|---|---|
|
|
This parameter controls the visibility and color theme of player controls (play/pause, mute/unmute, closed captions, and the legal text “i” icon) to ensure sufficient contrast over the video background.
Required:
Default:
There are two default theme options for the control elements to ensure visibility over any video file provided: It can have one of the following values:
|
|
|
Standard option to open the link on current page or new page.
Ignored if no
Values:
|
|
|
Legal text add-on for the video.
Max
Desktop: visible on hover of the “i” icon; Mobile / App: always visible below the video. |
|
|
Video background color.
Required:
Default:
|
|
|
Video alt text.
Required:
|
|
Key |
Description |
|---|---|
|
|
A URL to load a VAST XML that includes all information to render the video part (left side). |
|
OR |
* |
|
|
A VAST XML to provide a video player |
|
Attribute |
Specification |
|---|---|
|
File size |
300 MB |
|
Supported file types |
MP4 |
|
Video ratio |
9:16 |
|
Min duration |
4 seconds |
|
Max duration |
30 seconds |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
90 characters, including spaces |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
120 characters, multi-line text field |
|
Attribute |
Specification |
|---|---|
|
File type |
|
|
Encoding |
UTF-8 |
|
Attribute |
Specification |
|---|---|
|
Redirection URL |
There are two possible redirection options:
|
## What's next * [Ad Rendering Best Practices](/retailer-integration/docs/ad-rendering-best-practices) # Get started with Commerce Onsite Video Source: https://developers.criteo.com/retailer-integration/docs/commerce-video-integration Get started with the Onsite Video integration process This document provides development guidelines related to **Commerce Onsite Video formats**. This documentation section will provide you with detailed guidelines to: * fetch and render Commerce Onsite Video formats, with [API responses examples](/retailer-integration/docs/api-response-structure); * see the [full video player specifications](/retailer-integration/docs/video-player-specifications); * [track ad-related activity surrounding the Commerce Onsite Video formats](/retailer-integration/docs/tracking-ad-related-activity); * [implement the video player (Desktop and Mobile)](/retailer-integration/docs/video-player-implementation-guide-desktopmobile); * implement the video player (App) for Android and iOS: *coming soon*.
## What's next * [API response structure](/retailer-integration/docs/api-response-structure) * [Video player specifications](/retailer-integration/docs/video-player-specifications) * [Tracking ad-related activity](/retailer-integration/docs/tracking-ad-related-activity) * [Video player implementation (desktop/mobile)](/retailer-integration/docs/video-player-implementation-guide-desktopmobile) # Commerce Video Spotlight Source: https://developers.criteo.com/retailer-integration/docs/commerce-video-spotlight Commerce Video Spotlight combines a branded 16:9 video with an interactive product zone that adapts to desktop and mobile layouts. # Overview The Commerce Video Spotlight format contains a video section with controls, and a product zone. On desktop, the product zone is presented beside the video. On mobile, the product zone appears below the video.
|
Key |
Description |
|---|---|
|
|
Legal text add-on for the video. Max 90 characters long including spaces.
|
|
|
\_(only applicable for web). Can be ignored if no
Redirection target, can have the following values:
|
|
|
Video alternative text |
|
|
There are two default settings for the legal text box, buttons, and options (
It can have one of the following values:
|
|
Key |
Description |
|---|---|
|
|
A URL to load a VAST XML that includes all information to render the video. |
|
OR |
\- |
|
|
A VAST XML to provide a video player |
|
Attribute |
Specification |
|---|---|
|
File size |
≤300 MB |
|
Supported file types |
MP4 |
|
Video ratio |
16:9 |
|
Min duration |
4 seconds |
|
Max duration |
30 seconds |
|
Max dimensions |
640 x 360 px |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
90 characters (including spaces) |
|
Attribute |
Specification |
|---|---|
|
Maximum characters |
120 characters, multi-line text field |
|
Attribute |
Specification |
|---|---|
|
File type |
|
|
Encoding |
UTF-8 |
|
Condition |
Behavior |
|---|---|
|
|
Opens the target URL |
|
No
|
Video toggles play/pause |
* When hovering the **(i)** icon, the legal text is displayed on top of the video like so:
* On mobile screens, the legal text will always display between the **branding video zone** and the **product zone**, increasing the unit's total height.
#### Desktop (placement width > 445 px) * When multiple products are available, the navigation arrows always have the same position within the product zone. Arrows design is customizable to match the retailer UI and native components. * When only one product is available, the navigation arrows are no longer displayed and the product listing is centered horizontally and vertically in the product zone.
#### Mobile (placement width ≤ 445 px) * There is 10 px padding around each product listing.
## What's next * [Branding Video Standout](/retailer-integration/docs/branding-video-standout) * [Commerce Video Grid Duet](/retailer-integration/docs/commerce-video-grid-duet) # Criteo-Owned Video Player Integration Source: https://developers.criteo.com/retailer-integration/docs/criteo-owned-video-player-integration ## Purpose This guide explains how to integrate the Criteo-owned video player into your website to serve video ads within web applications. It handles the technical details of parsing VAST ads and managing video playback, supports accessibility features such as keyboard navigation and closed captioning, and includes OMID integration for accurate ad viewability tracking according to industry standards.
## What's next * [Video player implementation (App: iOS)](/retailer-integration/docs/video-player-implementation-app-ios) * [Video Player Implementation (Web Browser)](/retailer-integration/docs/video-player-implementation-guide-desktopmobile) # Digital Shelf Talker Source: https://developers.criteo.com/retailer-integration/docs/digital-shelf-talker Specifications for the Digital Shelf Talker Ad format # Introduction **Digital Shelf Talker is a responsive vertical display banner with a still image and a redirect link**. Points to remember: * Available within the grid. Redirects to 1 URL: * On desktop via **Branding Zone** and **call-to-action button**, * On mobile via **Branding Zone**.
|
Field |
Description |
|---|---|
|
|
URL of Background image file for desktop |
|
|
Alternative text for desktop background image |
|
|
URL of Background image file for mobile |
|
|
Alternative text for mobile background image |
|
|
Background color hexa code of the creative tile |
|
|
Web URL that the user should be redirected to |
|
|
App deeplink that the user should be redirected to |
|
|
Redirection target, can have the following values:
(only applicable for web) |
|
|
Button text (not applicable for mobile version) |
|
|
Button text color (not applicable for mobile version) |
|
|
Button background color (not applicable for mobile version) |
***
## What's next * [IAB](/retailer-integration/docs/iab) * [Display Panel](/retailer-integration/docs/display-panel) # Digital Shelf Talker Source: https://developers.criteo.com/retailer-integration/docs/digital-shelf-talker-1 Here is a breakdown of the requirements for your Digital Shelf Talker placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Redirection button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Redirection button text length |
Ensure that the button text supports up to 20 characters in length. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
*** ## Mobile version The creative width is equal to 100% of the parent div. It scales in proportion. When the width reduces, the height reduces as well. The background image is never cropped.
* `1400x300px` with a safe zone of `750x300px`
|
Field |
Description |
|---|---|
|
|
URL of Background image file for desktop |
|
|
Alternative text for desktop background image |
|
|
URL of Background image file for mobile |
|
|
Alternative text for mobile background image |
|
|
Web URL that the user should be redirected to |
|
|
App deeplink that the user should be redirected to |
|
|
Redirection target, can have the following values:
(only applicable for web) |
# Display Panel Source: https://developers.criteo.com/retailer-integration/docs/display-panel-1 Here is a breakdown of the requirements for your Display Panel placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
## What's next * [Ad Rendering Best Practices](/retailer-integration/docs/ad-rendering-best-practices) # Flagship Source: https://developers.criteo.com/retailer-integration/docs/flagship # Introduction **Flagship is a Commerce Display unit combining branded assets with product tiles**.
|
Key |
Description |
|---|---|
|
|
URL of the background image file for desktop/tablet app |
|
|
Alternative text for desktop background image |
|
|
URL of the background image file for mobile |
|
|
Alternative text for mobile background image |
|
|
Hex code for the format's outline color |
|
|
Can have the following values:
|
|
|
URL that the user should be redirected to |
|
|
Deeplink app that the user should be redirected to |
|
|
Redirection target, can have the following values:
(only applicable for web) |
|
|
URL of the file that the user would download after clicking |
|
Field |
Description |
|---|---|
|
|
The product that should be rendered when the button is clicked. The array is contains the priority order of product rendering. If you are checking product availability in real time, you should render the first available product in the array, i.e., if the first product is not available, check the second one, then check the third, and so on. |
|
|
If
If
|
## What's next * [Showcase](/retailer-integration/docs/showcase) * [Butterfly](/retailer-integration/docs/butterfly) * [Branded Header](/retailer-integration/docs/branded-header) * [Interactive Header](/retailer-integration/docs/interactive-header) # Flagship Source: https://developers.criteo.com/retailer-integration/docs/flagship-1 Here is a breakdown of the requirements for your Flagship placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all of the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both This beacon should be fired on every click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Differing product counts |
Ensure that the design for a single product matches the mock-ups and that all parts of the ad unit (SKUs, navigation arrows, navigation dots, buttons, etc.) ahere to the mock-ups when multiple products are returned. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Single product navigation |
Ads display without navigation arrows for both desktop and mobile and there are no "navigation dots" on the mobile carousel. |
Yes |
|
Multi-product navigation |
Ads display with navigation arrows for both desktop and mobile and there are "navigation dots" on the mobile carousel. |
Yes |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
|
Parameter |
Type |
Example(s) |
Description |
Required |
|---|---|---|---|---|
|
|
int |
|
The key that corresponds with your specific partner ID within Criteo. Please reach out to your Technical Account Manager to set up if needed. |
Yes |
|
|
string |
|
The page name as exposed in the Criteo configuration. Please reach out to your Technical Account Manager to set up if needed. |
Yes (can be hardcoded) |
|
|
string |
|
The placement name as exposed in the Criteo configuration. Please reach out to your Technical Account Manager to set up if needed. |
Yes (can be hardcoded) |
|
|
string |
|
A unique
|
Yes |
|
|
string |
|
Contextual data that can be any of: A keyword, A category, A SKU ID. Delivery will use the page type to determine how to use this context data to look up ads. |
Required for all page types except homepage |
|
|
URL encoded JSON |
URL Encoded:
URL Decoded:
|
Used to pass extra data for rendering purpose only. In this example, the lang parameter would be used to select the ad language to render.
It can be accessed from the creative response using:
|
No (optional) |
|
|
URL encoded JSON |
URL Encoded:
URL Decoded:
|
Used to pass extra data for to populate dynamically the passback tag only.
It can be accessed from the Passback tag using:
|
No (optional) |
|
|
string |
|
|
No (optional) |
|
|
string |
|
Store ID selected by the user when browsing the retailer’s site. It should match the store IDs in the product feed. See more details here . |
Yes, if Store IDs are defined in the product feed |
|
|
string |
|
Indicates if GDPR applies to this user. (1: yes, the user is in Europe and GDPR applies; 2: no, the user is outside Europe). |
Yes, if using TCFv2 standard |
|
|
string |
|
The encoded TCFv2 consent string. |
Yes, if using TCFv2 standard |
|
|
bit |
|
Value '1' is for opt-out users. (Value '0' can also be passed for opt-in users.) |
No, only when the user is opt-out and not using the TCFv2 standard |
# IAB Source: https://developers.criteo.com/retailer-integration/docs/iab IAB banners are static display units that redirect to a dedicated URL
|
Field |
Description |
|---|---|
|
|
URL of Background image file for desktop, mobile & app |
|
|
Alternative text for background image file for desktop, mobile & app |
|
|
Web URL that the user should be redirected to |
|
|
App deeplink that the user should be redirected to |
|
|
Redirection target, can have the following values:
(only applicable for web) |
# IAB Source: https://developers.criteo.com/retailer-integration/docs/iab-1 Here is a breakdown of the requirements for your IAB placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
*** ## Available options ### Redirection * At the banner's click, it redirects to the link defined in the response. * There are two redirection options * `_Self_` (redirect in same tab) * `_Blank_` (redirect in new tab) *** ### PDF file upload * A brand may choose for the CTA to result in a file download. This file will be included in the ad response. * At the banner's click, a PDF file opens like a redirection link with both `_Self_` and `_Blank_` options (see above) *** ### CTA buttons The banner will look like the following with the CTA button (with four buttons, three buttons, two buttons, no button).
# Interactive Header Source: https://developers.criteo.com/retailer-integration/docs/interactive-header-1 Here is a breakdown of the requirements for your Interactive Header placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all of the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both This beacon should be fired on every click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Product button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Product button text |
Ensure the name can fit on two lines and supports at least 20 characters of text |
Yes |
|
Redirection button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Redirection button text |
Ensure that the button text supports up to 20 characters in length. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Product navigation |
Ads display without navigation arrows for both desktop and mobile and there are no "navigation dots" on the mobile carousel. |
Yes |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
## What's next * [Beacon types](/retailer-integration/docs/beacon-types) * [Legacy & Universal beacons](/retailer-integration/docs/legacy-universal-beacons) * [BeaconSDK](/retailer-integration/docs/beacon-sdk) * [Server-Side Beacons](/retailer-integration/docs/server-side-beacons) * [Ad Tracking best practices](/retailer-integration/docs/ad-tracking-best-practices) # Legacy & Universal Beacons Source: https://developers.criteo.com/retailer-integration/docs/legacy-universal-beacons This page outlines Criteo's Legacy and the Universal beacon setups and explains how to migrate from Legacy to Standard/Universal beacons # Overview
|
Feature |
Legacy beacons |
Standard/Universal beacons |
|---|---|---|
|
Data transmission |
Sends an
|
Includes product data at the placement level |
|
Performance impact |
Higher network requests and load |
More efficient, fewer requests |
|
Implementation complexity |
Requires per-product tagging |
Consolidated tracking logic |
|
Use case |
Legacy setups requiring detailed per-product tracking |
Modern implementations optimizing efficiency |
|
Feedback mechanism |
No feedback on missing products |
Supports status codes for suppressed/not rendered products |
|
Optimization potential |
Limited visibility into why products didn't appear |
Enables fill rate optimization and revenue improvement |
## What's next * [BeaconSDK](/retailer-integration/docs/beacon-sdk) * [Server-Side Beacons](/retailer-integration/docs/server-side-beacons) * [Ad Tracking Best Practices](/retailer-integration/docs/ad-tracking-best-practices) # Mobile Deeplinks Guide for Offsite Source: https://developers.criteo.com/retailer-integration/docs/mobile-deeplinks-guide-for-offsite-app-integrations ## Introduction Deep linking enables users to be redirected to specific content within a mobile application when they click on a link. It provides a seamless transition between web and app environments, enhancing user experience and conversion potential. In mobile contexts, a deep link can take users directly to a screen or feature within the app. When a user taps one of these links, the mobile operating system (iOS or Android) launches the app and navigates to the desired content. At Criteo, **Offsite Retail Media for App** currently supports the following deep linking methods: * **Universal Links** on iOS, * **App Links** on Android.
|
Zone |
Description |
Requirement |
|---|---|---|
|
Logo Zone |
Contains advertiser branding (typically top-left). Redirects to the app’s main screen. |
Mandatory: Universal/App Link to main screen. |
|
Product Zone |
Displays products from the catalog. Redirects to product detail screens. |
Mandatory: Product-specific Universal/App Link. |
|
Coupon Zone |
Optional area showing discounts or special offers. |
Optional: Universal/App Link to main or promotional screen (e.g., category or search page). |
|
Platform |
Supported Method |
Fallback |
Required Configuration |
|---|---|---|---|
|
iOS |
Universal Links |
Mobile Web |
AASA file + Associated Domains |
|
Android |
App Links |
Mobile Web |
|
# Offsite Add-on — FPM Identification Call Source: https://developers.criteo.com/retailer-integration/docs/offsite-add-on-fpm-identification-call ## Introduction If you already have a live Retail Media integration, you are close to running Offsite campaigns. The Offsite Add-on reuses your existing setup, product feed, API calls, and onsite events, and adds one new piece: an **identification call** that links your first-party user ID to Criteo's identity graph. `/fpm/init` is that identification call. It associates your first-party visitor ID (RVI) and your retailer account with Criteo's internal identifiers, so the Retail Media events you already send become available for Offsite targeting and measurement. ## Prerequisites * Your onsite Retail Media solution is live and delivering ads. * You have a stable first-party user identifier (RVI). * The identification call must be triggered from the browser (not server-side). * You have received from your Criteo representative: * **Retailer ID** (`retailer_id`) * On every identification call you pass (all required): * `first_party_id`: your stable RVI (same value as in your Retail Media integration) * `retailer_id`: Criteo-issued retailer identifier * `first_party_name`: friendly name for your retailer or site (used in logs and diagnostics) ## Concept definitions * **Onsite**: ads rendered on your site or app using your first-party traffic. * **Offsite**: ads delivered outside your site, using your first-party data to reach shoppers on external inventory. * **RVI** (Retailer Visitor ID): your stable, persisted first-party identifier for a visitor. Use it as `first_party_id` in calls to `/fpm/init`. ## Retail Media API events (`full_url`) The Offsite add-on reuses the **Retail Media API events you already send**. In addition to the `/fpm/init` identification call, confirm that those event calls include `full_url` set to the **full page URL** where the event occurred (for example `https://shop.example.com/path?query=1`), not only the domain (for example `shop.example.com`). Many integrations send the domain alone; that is **not sufficient** for Offsite via this flow. Audit your payloads before go-live and validate with your Criteo contact in staging. ## Consent You should apply **privacy by design**: when the user has **not** granted consent, your site must **not** load third-party tags, including the Criteo Offsite identification call to `https://gum.criteo.com/fpm/init`. Only when consent for Criteo is granted should that call be triggered. Make sure you have a solution in place that controls whether the Criteo call runs (for example your CMP, tag manager, or equivalent). If consent is not granted, the Criteo Offsite call must not run at all. If consent to Criteo is granted, then trigger the Offsite identification call. If you do not have such a solution in place, contact Criteo support, we can help you implement **Criteo's solution** for handling consent alongside this integration. **Note:** This guide does **not** document Criteo's server-side consent evaluation in detail. Customer-facing guidance is to **gate the call** on the client unless Criteo has agreed a different pattern with you. Query keys such as `gdpr`, `gdpr_consent`, `us_privacy`, `gpp`, and `gpp_sid` are intentionally omitted from this guide.
|
Event |
Key |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
|
Criteo Account/Partner ID, provided by your technical contact. |
Yes |
|
|
|
|
A unique, unauthenticated user ID valid for at least 30 days. Used to track visitor behavior across sessions. Typically retrieved via a first-party cookie. |
Yes |
|
|
|
|
A consistent, internal ID for logged-in users, linked to accounts, purchase history, or membership programs. |
Highly recommended to improve x-device ROAS and enable in-store sales attribution. |
|
|
|
|
User’s email address in SHA256 hash format. |
Highly recommended to improve offsite retargeting. |
|
|
|
|
Device type:
|
No |
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed \[includes regiondata]\(tps\://developers.criteo.com/retailer-integration/docs/feed-parameters#regional-datahttps\://developers.criteo.com/retailer-integration/docs/product-feed-parameters#regional-data. |
## Browse Page For all category or taxonomy browse pages displaying a grid/list of products, or if you display a\ tailored collection of products, specify in the tag the universal events as well as the `viewCategory` event and its associated parameters:
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
IDs of the organic products shown, matching the IDs passed in the product feed. Used for deduplication. |
Required for ad de-duplication. Recommended for offsite targeting and audience building. |
|
|
|
|
The page number that the user is browsing. Make sure to re-fire the tag as the user navigates through each page so that fresh ads can be requested and rendered. |
Recommended to vary ad selection as the user navigates the grid. |
|
|
|
|
Category path, matching the
|
Yes |
|
|
|
|
Restricts ad response to specific attributes. Ensure these filter names and values match exactly what is passed in the feed. A list of accepted filter operators can be found here . |
Recommended to improve relevant advertising on filtered pages. |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata |
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
Enter this hardcoded value when there is no product grid on listing pages |
No |
|
|
|
|
Category path, matching the
|
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed \[includes regiondata]\(tps\://developers.criteo.com/retailer-integration/docs/feed-parameters#regional-datahttps\://developers.criteo.com/retailer-integration/docs/product-feed-parameters#regional-data . |
## Search Page For all search result pages displaying a grid/listing of products, specify in the tag the universal events as well as the following additional parameters.
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
IDs of the organic products shown, matching the IDs passed in the product feed. Used for deduplication. |
Required for ad de-duplication. Recommended for offsite targeting and audience building. |
|
|
|
|
The page number that the user is browsing. Make sure to re-fire the tag as the user navigates through each page so that fresh ads can be requested and rendered. |
Recommended to vary ad selection as the user navigates the grid. |
|
|
|
|
User-entered search term. If you perform a spell check internally before rendering results, please pass in the *corrected* keyword. |
Yes |
|
|
|
|
Restricts ad response to specific attributes. Ensure these filter names and values match exactly what is passed in the feed . A list of accepted filter operators can be found here . |
Recommended to improve relevant advertising on filtered pages. |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
## Null search result page For all search result pages not displaying any products, specify in the tag the universal events as well as the following additional parameters.
|
Key |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
Enter this hardcoded value when there is no product grid on listing pages |
No |
|
|
|
|
User-entered search term. If you perform a spell check internally before rendering results, please pass in the *corrected* keyword. |
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
## Product Detail Page
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
SKU ID of the currently visited product. Must match the value passed in the
|
Yes |
|
|
|
|
The parent ID of the currently visited product. Must match the value passed in the
|
No |
|
|
|
|
The current unit price of the visited product, leveraged for real-time updates in Criteo's system. |
Yes |
|
|
|
|
Product availability:
|
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
|
|
|
|
Category path, matching the \`product\_type\_key passed in the feed. If not passed, Criteo defaults to the primary taxonomy of the SKU in the item parameter. |
No |
## Add-to-cart event
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
Use the same
|
This is not a page view, but rather an event that takes place after the page has been loaded. For that reason, the page\_id remains unchanged from the initial page load. |
Yes |
|
|
|
|
A product array for the SKU added to the basket with ID,
unit
price, and quantity. IDs must match the
|
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
## Basket page
|
Parameter |
Event |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
If empty:
If populated:
|
An array of products in the basket with ID,
unit
price, and quantity. IDs must match the
|
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
## Order confirmation page
|
Event |
Parameter |
Example value |
Description |
Required? |
|---|---|---|---|---|
|
|
|
EMEA:
AMER:
|
Use standard page IDs unless otherwise specified. |
Yes |
|
|
|
|
The unique order/transaction ID of the completed purchase |
Yes |
|
|
|
|
An array of products in the order with ID,
unit
price, and quantity. IDs must match the
|
Yes |
|
|
|
|
The ID of the specific store that the user is browsing. |
Only pass this value if your product feed includes regiondata . |
## What's next * [OneTag for existing CMS retailer](/retailer-integration/docs/onetag-for-existing-cms-retailer) * [OneTag for Offsite](/retailer-integration/docs/onetag-for-offsite) # OneTag for Retail Media Offsite Source: https://developers.criteo.com/retailer-integration/docs/onetag-for-offsite # Introduction
|
Event |
Key |
Example value |
Description |
|---|---|---|---|
|
|
account |
|
Your Criteo Account or Partner ID, provided by your technical contact, to route data to Criteo servers. |
|
|
id |
|
A unique, unauthenticated user ID valid for at least 30 days. Used to track visitor behavior across sessions. Typically retrieved via a first-party cookie. |
|
|
id |
|
A consistent, internal ID for logged-in users, linked to accounts, purchase history, or membership programs. |
|
|
|
|
User’s email address in SHA256 hash format. *Please pass an empty string if the user's email is unavailable.* |
# OneTag for Offsite - Hybrid Apps Source: https://developers.criteo.com/retailer-integration/docs/onetag-offsite-for-hybrid-apps Addendum for Hybrid Apps # Introduction This guide is to be used in 2 different scenarios: * Hybrid app integration for offsite and onsite, already integrated through API * Hybrid app integration for offsite only.
# Checklists per format Source: https://developers.criteo.com/retailer-integration/docs/qa-checklists
|
Header |
Required |
Purpose |
|---|---|---|
|
|
Yes |
Includes original user IP |
|
|
Yes |
Identifies client device/browser |
|
|
Recommended |
Provides page context |
## What's next * [Ad Tracking Best Practices](/retailer-integration/docs/ad-tracking-best-practices) # Showcase Source: https://developers.criteo.com/retailer-integration/docs/showcase # Introduction **Showcase is a Commerce Display unit combining branded assets with product tiles**.
|
Field |
Description |
|---|---|
|
|
URL of the background image file for desktop / tablet app |
|
|
Alternative text for desktop background image |
|
|
URL of the background image file for mobile |
|
|
Alternative text for mobile background image |
|
|
Format outline color hexa code |
|
|
Background color hexa code of the creative tile |
|
|
Title of format (above the format) |
|
|
Title of format color hexa code |
|
|
*For first option:* Option type. Can have the following values:
|
|
|
*For first option:* Optional text (non-applicable for mobile version) |
|
|
*For first option:* URL web that the user should be redirected to |
|
|
*For first option:* App deeplink that the user should be redirected to |
|
|
*For first option:* Redirection target, can have the following values:
(only applicable for web) |
|
|
*For first option:* URL of media file |
|
|
*For first option:* Option text color |
|
|
*For first option:* Option background color |
|
|
*For second option:* Option type. Can have the following values:
|
|
|
*For second option:* Option text (non-applicable for mobile version) |
|
|
*For second option:* URL web that the user should be redirected to |
|
|
*For second option:* App deeplink that the user should be redirected to |
|
|
*For second option:* Redirection target, can have the following values:
(only applicable for web) |
|
|
*For second option:* URL of media file |
|
|
*For second option:* Option text color |
|
|
*For second option:* Option background color |
|
Field |
Description |
|---|---|
|
|
The product that should be rendered when the button is clicked. The array is contains the priority order of product rendering. If you are checking product availability in real time, you should render the first available product in the array, i.e., if the first product is not available, check the second one, then check the third, and so on. |
|
|
If
If
|
## What's next * [Butterfly](/retailer-integration/docs/butterfly) * [Branded Header](/retailer-integration/docs/branded-header) * [Interactive Header](/retailer-integration/docs/interactive-header) # Showcase Source: https://developers.criteo.com/retailer-integration/docs/showcase-1 Here is a breakdown of the requirements for your Showcase placement to pass both technical and design QA # Beaconing
|
Level |
Name |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Format |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For display ads, the placement is considered "loaded" when the entire unit is rendered. This beacon should only be fired once. |
Yes |
|
Format |
View |
|
URL to be called when the placement is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the unit must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Format |
Click |
|
URL to be called when the user clicks on the placement itself. |
Yes |
|
Format |
File download |
|
URL to be called when a click is made by the user on a CTA button, or from the creative image of the format, which leads to a file download. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all of the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both This beacon should be fired on every click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
|
Yes |
|
Redirection button formatting |
Ensure that the button's shape, font, font size, and position are aligned with the provided mock-ups. |
Yes |
|
Redirection button text |
Ensure that the button text supports up to 20 characters in length. |
Yes |
|
Mockup adherence |
The design of the mock-ups should be followed, ensuring the following:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Option |
Check |
Mandatory |
|---|---|---|
|
No redirection |
Nothing happens |
Yes |
|
Redirection URL |
The user gets redirected to the URL provided in the ad response |
Yes |
|
File download |
The user downloads the file provided |
Yes |
|
Attributes |
Format |
Description |
|---|---|---|
|
|
|
Alerts to whether the API call succeeded or failed |
|
|
Array of strings |
Only appears if the
|
|
|
Array of objects:
|
Lists all placements available for the specific page-id the API is being called for (example:
|
|
Attributes |
Format |
Description |
|---|---|---|
|
|
Array of objects:
|
Lists all formats present for the placement |
|
|
Empty string |
Internal use |
|
|
Empty string |
Not in use for Sponsored Products |
|
|
String containing a URL |
You can find more information on the beacons in the next chapter |
|
Attributes |
Format |
Description |
|---|---|---|
|
|
String |
Product ID of the product that matches what Criteo has in the product feed |
|
|
String |
Values that are in the feed, describing the
|
|
|
String containing a JSON object |
Values in the feed that are not standard, but are needed to render the ad. If you need these, contact your Criteo representative |
|
|
String |
Internal ID |
|
|
String |
Criteo ID of the advertiser who sent the ad |
|
|
String containing a URL |
More information on the beacons can be found in the next chapter |
## What's next * [Onsite Display (New)](/retailer-integration/docs/onsite-display-new-formats) * [Video Formats](/retailer-integration/docs/video-formats) * [Ad Rendering best practices](/retailer-integration/docs/ad-rendering-best-practices) * [Introduction to beacons](/retailer-integration/docs/introduction-to-beacons) # Sponsored Products Source: https://developers.criteo.com/retailer-integration/docs/sponsored-products-1 Here is a breakdown of the requirements for your sponsored product placement to pass both technical and design QA: # Beaconing
|
Level |
Title |
Response field |
Explanation |
Mandatory |
|---|---|---|---|---|
|
Placement |
Impression |
|
URL to be called when the whole placement is loaded onto the page. For sponsored products, the placement is considered "loaded" when at least one product is rendered. |
Yes |
|
Placement |
View |
|
URL to be called when at least 50% of the first product is in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once. |
Yes |
|
Product |
Impression |
|
URL to be called when the individual product tile is loaded onto the page. If leveraging universal beacons , this field will be blank. This beacon should only be fired once. |
Yes |
|
Product |
View |
|
URL to be called when the individual product tile is viewed according to IAB's viewable ad impression measurement guidelines. At least 50% of the placement must be in the user's viewport for at least 1 uninterrupted second. This beacon should only be fired once per product. |
Yes |
|
Product |
Click |
and/or
|
productPage
This element is a URL that will send an
It is possible to use this as the
onClickBeacon URL to be called when the individual product tile is clicked. This refers to *any* click interaction with the product tile outside of adding to cart or adding to wishlist (see next two rows). This beacon should fire on all the range of clicks; left click, middle click, right click to open in a new tab and keyboard shortcuts that simulate a click. Both
This label refers to cases where both
Deduplication is performed only when multiple beacons of the same type are received. Criteo will handle this deduplication internally for billing purposes. |
Yes |
|
Product |
Add-to-cart |
|
URL to be called when a product is added to or removed from the basket/cart. You can add the quantity of products as a query string parameter. If no
This beacon should be fired on *every* add-to-cart click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Product |
Add-to-wishlist |
|
URL to be called when the product is added to the wishlist/favorites. This beacon should be fired on *every* add-to-wishlist click event. Criteo will deduplicate clicks for billing purposes internally. |
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Breakpoint adherence |
For each window size (breakpoint), ensure the sponsored products are positioned properly and that all "sponsored" badges are displayed correctly, as shown in the mock-ups provided by Criteo. |
Yes |
|
Mock-up adherence |
The design of the mock-ups should be followed as specified:
|
Yes |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Filters leveraged in ad calls |
|
Yes, if filters have been implemented |
|
Leveraging regiondata |
|
Yes, if regiondata has been implemented |
|
Check |
Explanation |
Mandatory |
|---|---|---|
|
Test purchase |
|
Yes |
|
Beacon Name |
Beacon Description |
|---|---|
|
|
Indicates that the format (video + SKUs if applicable) is rendered on the page, even if not viewable yet. |
|
|
Indicates that the format is viewed by the user (viewability = more than 50% of the format in the user's viewport for 1 second). \_Note: this indicates the viewability of the format. However, video viewability (more than 50% of the format in the user’s viewport for two consecutive seconds) is tracked with OMID capabilities (see the "Additional verification with OMID compatible scripts” section). This beacon is not used to track video viewability.\_ |
|
|
Indicates that the format has been clicked by the user on a clickable and redirectable element that is neither the video nor the product tile (example: a CTA, a clickable text around the video...). If there is no any other clickable element than the video or SKUs, you can ignore this beacon. *Notes:*
2. Clicks on the video itself should use the click tracking beacon in the VAST XML.\_ |
|
|
Please disregard this beacon. |
|
|
Please disregard this beacon. |
|
Beacon Name |
Beacon Description |
|---|---|
|
|
Indicates that the product tile is rendered on the page (even if not viewable yet). |
|
|
Indicates that the product tile is viewed by the user (viewed = more than 50% of the product in the user's viewport for 1 second). |
|
|
This beacon is triggered when a user clicks on an element (image, text) of the product tile that redirects to the product page. |
|
|
This beacon is triggered when the user adds a product to their cart.
\_If there is no
|
|
|
This beacon is triggered when the user adds a product to their wishlist.
\_If no add-to-Wishlist CTA is available, it can be disregarded. The beacon can be fired multiple times if the user repeatedly clicks the
|
|
Name |
Description |
|---|---|
|
|
Indicates that the video is rendered on the page (even if not viewable yet). Not used for billing. |
|
|
Indicates that the video has started and should be triggered when the video enters in 50% of the user’s viewport. This is the beacon used for impression billing and reporting. |
|
|
Must be triggered when 25% of the video has been played. |
|
|
Must be triggered when 50% of the video has been played. |
|
|
Must be triggered when 75% of the video has been played. |
|
|
Must be triggered when 100% of the video has been played. |
|
|
Must be triggered every time the user clicks on the video and gets redirected to the landing page stored in the
\_Do not trigger this beacon for clicks on the interactive buttons (
|
|
|
Must be triggered every time the user clicks the
\_This action must not be triggered at the start of the video. It should only be initiated when the user actively mutes the video by clicking the
|
|
|
Must be triggered every time the user clicks the
|
|
|
Must be triggered every time the user clicks the
*If the decision is made not to display a pause/resume button in the player, this beacon can be ignored. This beacon should only be triggered by the button click and should not be triggered when the video pauses by itself due to leaving the viewport.* *If there is no redirection link provided in the VAST XML, a click on the video itself should pause/resume the video and this beacon should be fired.* |
|
|
Must be triggered every time the user clicks the
*If the decision is made not to display a pause/resume button in the player, this beacon can be ignored. This beacon should only be triggered by the button click and should not be triggered when the video autonomously resumes after being paused by leaving the viewport and subsequently returning.* *If there is no redirection link provided in the VAST XML, a click on the video itself should pause/resume the video and this beacon should be fired.* |
## What's next * [Criteo-Owned Video Player Integration](/retailer-integration/docs/criteo-owned-video-player-integration) # Video Formats Source: https://developers.criteo.com/retailer-integration/docs/video-formats Overview of the available Criteo Video Ad Formats This section presents the two video-based ad formats available for integration in Retail Media: * **Commerce Video Spotlight (CVS)** * **Branding Video Standout (BVS)** * **Commerce Video Grid Duet (CVGD)** Both leverage **VAST 4.2** for video delivery, support desktop and mobile layouts, and include configurable rendering keys for creative consistency across placements. *** ## Commerce Video Spotlight (CVS) CVS is a **commerce-focused format** combining a video and a shoppable product zone.\ It is designed to bridge **branding impact and product engagement**, it adapts responsively and supports optional interaction and styling parameters (e.g., legal text, color mode, redirect behavior). *** ## Branding Video Standout (BVS) BVS is a **storytelling-oriented format** that merges brand video, image, and message elements into a unified layout. It supports CTA interaction, consistent redirect logic, and a modular design that aligns with both awareness and commerce goals. *** ## Commerce Video Grid Duet (CVGD) CVGD is a **commerce-focused video format** that pairs a vertical branding video with a scrollable product zone. It supports a CTA redirection and responsive design for consistent performance across devices. ***
## What's next * [Commerce Video Spotlight](/retailer-integration/docs/commerce-video-spotlight) * [Branding Video Standout](/retailer-integration/docs/branding-video-standout) * [Commerce Video Grid Duet](/retailer-integration/docs/commerce-video-grid-duet) # Video Player Implementation (App: Android) Source: https://developers.criteo.com/retailer-integration/docs/video-player-implementation-app-android This document provides implementation guidance for integrating Onsite Video ads into native Android apps.
|
Parameter |
Description |
Default value |
|---|---|---|
|
|
Whether to automatically load VAST/assets on init. |
|
|
|
Initial mute state for the first play. |
|
|
|
Wrapper view background color. |
|
|
|
Loading overlay background color. |
|
|
|
ProgressBar indicator color while loading. |
|
|
|
Loading message text. |
"Loading video ad..." |
|
|
Loading text color. |
|
|
|
Error overlay background color. |
|
|
|
Error text color. |
|
|
|
Retry button label text. |
|
|
|
Retry button text color. |
|
|
|
Retry button background color. |
|