/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search
curl --request POST \
--url https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"attributes": {
"externalIds": [
"ss-146119-1726",
"ss-163828-1041"
]
},
"type": "ProductByExternalId"
}
}
'import requests
url = "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search"
payload = { "data": {
"attributes": { "externalIds": ["ss-146119-1726", "ss-163828-1041"] },
"type": "ProductByExternalId"
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
attributes: {externalIds: ['ss-146119-1726', 'ss-163828-1041']},
type: 'ProductByExternalId'
}
})
};
fetch('https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'externalIds' => [
'ss-146119-1726',
'ss-163828-1041'
]
],
'type' => 'ProductByExternalId'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"attributes": {
"additionalImageLinks": [
"https://www.acmefr.example/images/149559_1041_square_2.jpg"
],
"adult": false,
"adwordsGrouping": "backpacks",
"adwordsLabels": [
"summer-sale"
],
"adwordsRedirect": "https://www.acmefr.example/r/ss-149559-1041",
"ageGroup": "newborn",
"alternateIds": [
"ss-149559-1041-upc"
],
"availability": "inStock",
"availabilityDate": "2026-10-01T00:00:00Z",
"badge": "https://www.acmefr.example/badges/bestseller.png",
"beginEligibleDate": "2026-09-01T00:00:00.0000000+00:00",
"blockedDate": "2026-09-15T12:00:00.0000000+00:00",
"blockedMatch": "counterfeit",
"blockedType": "Keyword",
"brand": "Samsonite",
"category1": "Luggage & Bags",
"category2": "Backpacks",
"category3": "Laptop Backpacks",
"color": "Black",
"condition": "new",
"createdDate": "2026-09-01T08:30:00.0000000+00:00",
"crossSellersProductId": "XPD-4481",
"customLabel0": "BACKPACK&BAG",
"customLabel1": "summer",
"customLabel2": "outlet",
"customLabel3": "new-collection",
"customLabel4": "premium",
"deletedDate": "2026-09-20T10:00:00.0000000+00:00",
"description": "Round-shaped business casual backpack in leather.",
"discount": 15.5,
"displayable": true,
"displayAdsId": "da-149559-1041",
"displayAdsLink": "https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html?src=display",
"displayAdsTitle": "Sunfire Backpack",
"displayAdsValue": 0.35,
"endEligibleDate": "2026-12-31T23:59:59.0000000+00:00",
"energyEfficiencyClass": "A++",
"excludedChannels": [
"RM_OFFSITE"
],
"expirationDate": "2026-12-31T23:59:59.0000000+00:00",
"extra": {},
"filters": {},
"gender": "male",
"googleProductCategory": "Luggage & Bags > Cosmetic & Toiletry Bags",
"gtin": "5400520246585",
"hashedExternalId": 6482838394677175000,
"id": "ss-149559-1041",
"imageUrl": "https://www.acmefr.example/images/149559_1041_square_1.jpg",
"instock": true,
"itemGroupId": "ss-149559",
"lastUpdateDate": "2026-09-23T06:15:00.0000000+00:00",
"material": "Leather",
"mobileLink": "https://m.acmefr.example/sunfire/backpack/ss-149559-1041.html",
"mpn": "QT7*09001",
"multipack": 3,
"name": "Sunfire Backpack Black",
"numberOfReviews": 128,
"pattern": "Plain",
"price": 342000,
"productRating": "4.6",
"productType": "Backpacks > Sunfire",
"productTypeKey": "bp-sunfire",
"productUrl": "https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html",
"promoText": "Free shipping this week",
"promotionId": "PROMO-2026-09",
"promotionIds": [
"PROMO-2026-09",
"FREESHIP"
],
"recommendable": true,
"retailPrice": 399000,
"salePriceEffectiveDate": "2026-09-01T00:00:00Z/2026-09-30T23:59:59Z",
"sellerId": "seller-77",
"sellerName": "Bag World",
"sizes": [
"One Size"
],
"smallimage": "https://www.acmefr.example/images/149559_1041_small.jpg",
"unitPricingBaseMeasure": "100ml",
"unitPricingMeasure": "750ml"
},
"id": "ss-146119-1726",
"type": "ProductByExternalId"
}
],
"errors": [
{
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"source": {},
"stackTrace": "<string>",
"title": "<string>",
"traceId": "<string>",
"traceIdentifier": "<string>",
"type": "unknown"
}
],
"warnings": [
{
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"source": {},
"stackTrace": "<string>",
"title": "<string>",
"traceId": "<string>",
"traceIdentifier": "<string>",
"type": "unknown"
}
]
}/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search
Get specific products of a merchant from the product cache, by their external ids. This is a read: it is a POST only because the ids travel in the body. Ids that match no product of the merchant are left out of the response, so the result can be empty or shorter than the request.
POST
/
2027-01
/
marketing-solutions
/
catalog
/
merchants
/
{merchant-id}
/
details
/
products
/
search
/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search
curl --request POST \
--url https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"attributes": {
"externalIds": [
"ss-146119-1726",
"ss-163828-1041"
]
},
"type": "ProductByExternalId"
}
}
'import requests
url = "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search"
payload = { "data": {
"attributes": { "externalIds": ["ss-146119-1726", "ss-163828-1041"] },
"type": "ProductByExternalId"
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
attributes: {externalIds: ['ss-146119-1726', 'ss-163828-1041']},
type: 'ProductByExternalId'
}
})
};
fetch('https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'externalIds' => [
'ss-146119-1726',
'ss-163828-1041'
]
],
'type' => 'ProductByExternalId'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.criteo.com/2027-01/marketing-solutions/catalog/merchants/{merchant-id}/details/products/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"externalIds\": [\n \"ss-146119-1726\",\n \"ss-163828-1041\"\n ]\n },\n \"type\": \"ProductByExternalId\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"attributes": {
"additionalImageLinks": [
"https://www.acmefr.example/images/149559_1041_square_2.jpg"
],
"adult": false,
"adwordsGrouping": "backpacks",
"adwordsLabels": [
"summer-sale"
],
"adwordsRedirect": "https://www.acmefr.example/r/ss-149559-1041",
"ageGroup": "newborn",
"alternateIds": [
"ss-149559-1041-upc"
],
"availability": "inStock",
"availabilityDate": "2026-10-01T00:00:00Z",
"badge": "https://www.acmefr.example/badges/bestseller.png",
"beginEligibleDate": "2026-09-01T00:00:00.0000000+00:00",
"blockedDate": "2026-09-15T12:00:00.0000000+00:00",
"blockedMatch": "counterfeit",
"blockedType": "Keyword",
"brand": "Samsonite",
"category1": "Luggage & Bags",
"category2": "Backpacks",
"category3": "Laptop Backpacks",
"color": "Black",
"condition": "new",
"createdDate": "2026-09-01T08:30:00.0000000+00:00",
"crossSellersProductId": "XPD-4481",
"customLabel0": "BACKPACK&BAG",
"customLabel1": "summer",
"customLabel2": "outlet",
"customLabel3": "new-collection",
"customLabel4": "premium",
"deletedDate": "2026-09-20T10:00:00.0000000+00:00",
"description": "Round-shaped business casual backpack in leather.",
"discount": 15.5,
"displayable": true,
"displayAdsId": "da-149559-1041",
"displayAdsLink": "https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html?src=display",
"displayAdsTitle": "Sunfire Backpack",
"displayAdsValue": 0.35,
"endEligibleDate": "2026-12-31T23:59:59.0000000+00:00",
"energyEfficiencyClass": "A++",
"excludedChannels": [
"RM_OFFSITE"
],
"expirationDate": "2026-12-31T23:59:59.0000000+00:00",
"extra": {},
"filters": {},
"gender": "male",
"googleProductCategory": "Luggage & Bags > Cosmetic & Toiletry Bags",
"gtin": "5400520246585",
"hashedExternalId": 6482838394677175000,
"id": "ss-149559-1041",
"imageUrl": "https://www.acmefr.example/images/149559_1041_square_1.jpg",
"instock": true,
"itemGroupId": "ss-149559",
"lastUpdateDate": "2026-09-23T06:15:00.0000000+00:00",
"material": "Leather",
"mobileLink": "https://m.acmefr.example/sunfire/backpack/ss-149559-1041.html",
"mpn": "QT7*09001",
"multipack": 3,
"name": "Sunfire Backpack Black",
"numberOfReviews": 128,
"pattern": "Plain",
"price": 342000,
"productRating": "4.6",
"productType": "Backpacks > Sunfire",
"productTypeKey": "bp-sunfire",
"productUrl": "https://www.acmefr.example/sunfire/backpack/ss-149559-1041.html",
"promoText": "Free shipping this week",
"promotionId": "PROMO-2026-09",
"promotionIds": [
"PROMO-2026-09",
"FREESHIP"
],
"recommendable": true,
"retailPrice": 399000,
"salePriceEffectiveDate": "2026-09-01T00:00:00Z/2026-09-30T23:59:59Z",
"sellerId": "seller-77",
"sellerName": "Bag World",
"sizes": [
"One Size"
],
"smallimage": "https://www.acmefr.example/images/149559_1041_small.jpg",
"unitPricingBaseMeasure": "100ml",
"unitPricingMeasure": "750ml"
},
"id": "ss-146119-1726",
"type": "ProductByExternalId"
}
],
"errors": [
{
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"source": {},
"stackTrace": "<string>",
"title": "<string>",
"traceId": "<string>",
"traceIdentifier": "<string>",
"type": "unknown"
}
],
"warnings": [
{
"code": "<string>",
"detail": "<string>",
"instance": "<string>",
"source": {},
"stackTrace": "<string>",
"title": "<string>",
"traceId": "<string>",
"traceIdentifier": "<string>",
"type": "unknown"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
Identifies the merchant whose catalog products are read.
Body
application/json
The external ids to look up, between 1 and 500.
Request to look up products of a merchant by their external ids.
The lookup to perform, in the resource envelope of the API.
Show child attributes
Show child attributes
Response
200 - application/json
object | null
The products of the merchant that match the given external ids.
A list of ProductByExternalId resources in data, with the warnings and errors met while building it.
Was this page helpful?