API calls
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 |
|---|---|---|---|
Account ID | criteo-partner-id | Your Criteo Account ID, will be provided by your technical contact Ex: criteo-partner-id=102302 | Yes |
Retailer Visitor ID | retailer-visitor-id | Unauthenticated User ID, consistent across sessions Ex: retailer-visitor-id=c9623-aaaa | Yes |
Customer ID | customer-id | 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: customer-id=c9621-bbbb | Yes |
Email | email | Hash value of the user email address SHA256 Ex: 3786ae0aa4a0655c | Only if discussed with your Criteo team |
Test call | nolog | 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: nolog=1Can be used on preprod accounts. | Only if discussed with your Criteo team |
Item white list | item-whitelist | 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 |
Region ID | regionId | 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: regionId=123-abc|456-def|789-ghi | Only if discussed with your Criteo team |
Homepage
You will find an example of test retailer here.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
viewHome | page-id | The page ID should follow the format of: EMEA: viewHomeApi[Environment]AMER: viewHome_API_[Environment]Ex: viewHomeApiDesktop | Yes |
viewHome | event-type | We are using the viewHome for the homepage | Yes |
Category page
You will find an example of test retailer here.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
viewCategory | page-id | The page ID should follow the format of: EMEA: viewCategoryApi[Enviornment]AMER: viewCategory_API_[Environment]Ex: viewCategoryApiDesktop | Yes |
viewCategory | event-type | We are using the viewCategory for the browse | Yes |
viewCategory | item | 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: item=123|456|789 | Yes |
viewCategory | parent-item | The parent item ID of the organics products on the page, if the product has a parent ID. Ex: 12345|NULL|NULLThis should only be used if parent/child SKUs have been set up. | Only if discussed with your Criteo team |
viewCategory | page-number | The current page-number. Ex: page-number=2 | Recommended |
viewCategory | category | 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: category=1001 | Yes |
viewCategory | filters | Used to restrict the response to products which have a certain attribute with the exact value in the Feed Ex: filters=(brand,eq,nike) | Only if discussed with your Criteo team |
viewCategory | list-size | The total number of organic products that show on the page. Ex: list-size=24 | Recommended |
Search page
Here is an example of a test retailer.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
viewSearchResult | page-id | The page ID should follow the format of: EMEA: viewSearchResultApi[Environment]AMER: viewSearchResult_API_[Environment]Ex: viewSearchResultApiDesktop | Yes |
viewSearchResult | event-type | We are using the viewSearchResult for the search | Yes |
viewSearchResult | item | 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: item=123|456|789 | Yes |
viewSearchResult | parent-item | The parent item ID of the organics products on the page, if the product has a parent ID. Ex: 12345|NULL|NULLThis should only be used if parent/child SKUs have been set up. | Only if discussed with your Criteo team |
viewSearchResult | page-number | The current page-number. Ex: page-number=2 | Recommended |
viewSearchResult | keywords | The keyword which was entered by the user Ex: keywords=shoes | Yes |
viewSearchResult | filters | Used to restrict the response to products which have a certain attribute with the exact value in the Feed Ex: filters=(brand,eq,nike) | Only if discussed with your Criteo team |
viewSearchResult | list-size | The total number of organic products that show on the page. Ex: list-size=24 | Recommended |
Product page
Here is an example of a test retailer.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
viewItem | page-id | The page ID should follow the format of: EMEA: viewItemApi[Environment]AMER: viewItem_API_[Environment]Ex: viewItemApiDesktop | Yes |
viewItem | event-type | We are using the viewItem for the search | Yes |
viewItem | item | Item of the currently visited product. This ID needs to match with the ID provided in the feed Ex: item=123 | Yes |
viewItem | parent-item | 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: parent-item=123 | Only if discussed with your Criteo team |
viewItem | price | The current price of the product. This price will be used to update the product price on criteo's side in real time Ex: price=3.99 | Yes |
viewItem | list-price | Current non-discounted price / MSRP of the product. Ex: list-price=5.99 | Recommended |
viewItem | availability | 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: availability=1 | Yes |
Add-to-cart
You can find an example of a test retailer here.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
addToCart | page-id | For the page-id, you must use the ID of the page where the add-to-cart event took place. For example, if the user added a SKU to the cart directly from the product tile on a Search results page, the pageID for this call would be:EMEA: viewSearchResultApi[Environment]AMER: viewSearchResult_API_[Environment]Ex: viewSearchResultApiDesktop | Yes |
addToCart | event-type | We are using the addToCart for the add to cart page | Yes |
addToCart | item | Array of products in the basket, including SKUs that has to match the ID provided in the feed. Ex: item=123 | Yes |
addToCart | parent-item | 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: parent-item=123 | Only if discussed with your Criteo team |
addToCart | price | Array of products in the basket single unit price Ex: price=3.99 | Yes |
addToCart | quantity | Array of quantity of each product in the basket Ex: quantity=3 | Yes |
addToCart | page-uid | Unique ID present at the bottom of the API call of the current page. Ex: page-uid=1234567890 | Yes |
Basket page
You can find an example of a test retailer here.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
viewBasket | page-id | The page ID should follow the format of: EMEA: viewBasketApi[Environment]AMER: viewBasket_API_[Enviornment]Ex: viewBasketApiDesktop | Yes |
viewBasket | event-type | We are using the viewBasket for the basket | Yes |
viewBasket | item | Array of products in the basket, including SKU that has to match the ID provided in the feed. Ex: item=123 | Yes |
viewBasket | parent-item | 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: parent-item=123 | Only if discussed with your Criteo team |
viewBasket | price | Array of products in the basket single unit price Ex: price=3.99 | Yes |
viewBasket | quantity | Array of products in the basket overall quantity of the item Ex: quantity=3 | Yes |
Order confirmation page
You can find an example of a test retailer here.
| Title | Name | To Check | Mandatory |
|---|---|---|---|
trackTransaction | page-id | The page ID should follow the format of: EMEA: trackTransactionApi[Environment]AMER: trackTransaction_API_[Environment]Ex: trackTransactionApiDesktop | Yes |
trackTransaction | event-type | We are using the trackTransaction for the order confirmation | Yes |
trackTransaction | transaction-id | Unique order / transaction ID Ex: 51852389 | Yes |
trackTransaction | item | 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: item=123|456|789 | Yes |
trackTransaction | parent-item | 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: parent-item=123|456|NULL | Only if discussed with your Criteo team |
trackTransaction | price | Array of products in the basket single unit price Ex: price=3.99|10.00|0.99 | Yes |
trackTransaction | quantity | Array of products in the basket overall quantity of the item Ex: quantity=3|1|5 | Yes |
trackTransaction | currency | The local currency of the retailer should be added here Ex: GBP | This should only be used if discussed with your Criteo team |
Updated about 2 months ago