Where to make API calls

Our API recognizes the following page types:

• Search: Pages where users perform a keyword search, including the search bar dropdown.
• Category: Includes category pages, category menu fly outs, and deals/promotional pages.
• Product detail (PDP): Individual product pages.
• Homepage: The main landing page of your site.
• Checkout/Cart/Basket: Pages where users review their cart or initiate checkout.
• Order confirmation: Pages confirming a transaction or purchase.

There is also a special "page type" called add-to-cart. In practice, this is not a dedicated page, but an event used to build our keyword model. More information about the keyword model can be found here.

Each page type is linked to valid values of the event-type parameter in the API call. More details can be found at API Parameters.

Recommended API call practices

• Make ad calls on every page load: Ideally, make API calls on every page load to ensure comprehensive data collection and ad delivery.

• Prioritization guidelines: If offsite campaigns are planned, it's mandatory to have an API call at every page load. However, if making calls on every page load is not possible, follow this prioritization:

  1. Search pages: Essential for building the keyword model and typically the best performing page type. This is a mandatory page type.

  2. Transaction pages: Crucial for tracking attribution. This is a mandatory page type.

  3. Product detail pages: Important for building the keyword model and updating product prices and availability. If you are relying solely on the product data sent by the API to show your ads, without real-time product data checks, this page type should be considered mandatory. Implement calls here even if no ads are displayed.

  4. Category pages: Generally the second most performant page type. This is highly recommended.

  5. Homepage: Often has the most impressions, useful for campaigns with post-view attribution. This is recommended.

  6. Checkout pages: Used to decide recommended products based on cart contents. This is recommended.

• Rule of thumb: Assuming the ad zoning is already decided, implement mandatory pages first. You should not publish Criteo's integration without implementing at least all pages that will show ads and the transaction page.

• Add-to-cart events: Particularly useful if your ecommerce platform allows users to add products to their cart without needing to open the product detail page.

API endpoints

Criteo's Retail Media ad delivery system provides three different endpoints, separated by region, to ensure the closest data center is used based on the location of your servers.

Endpoint structure

1. Host: d.[region].criteo.com
   • Supported regions:
     • EMEA: eu
     • AMERICAS: us
     • APAC: as
2. Path: /delivery/retailmedia
3. Scheme: Always https
4. Query Parameters: Described in API Parameters

Possible endpoints

• EMEA: https://d.eu.criteo.com/delivery/retailmedia?[parameters]
• AMERICAS: https://d.us.criteo.com/delivery/retailmedia?[parameters]
• APAC: https://d.as.criteo.com/delivery/retailmedia?[parameters]

Usage guidelines

• Use the endpoint based on where your API calls will originate, not where your users or your frontend are located.
• If you are unsure of which endpoint to use, please ask your technical account manager for guidance.

API parameters

To receive ads from Criteo's delivery engine, a GET request must be made to our servers. The GET request must contain a specific set of parameters, which differ based on the type of page for which the call is made.

📘

The list of those parameters can be found here: API parameters