Skip to content

Catalog Item Search

Overview

Catalog Item Search API provides the capability to search "advertiser" items that are part of retail catalogs published on 'samsclub.com'.

Usage:

  • To search an item by providing search String text or item id
  • To create a new campaign in a draft state for a specific advertiser
  • To update an existing campaign using the PUT operation

Limitations:

  • Item search operation will yield a maximum of 200 primary variant items for an advertiser
  • There is no limit on the number of variant items that are returned for a primary variant item

Note: The suggested bid parameter is an automated bid-price recommendation based on winning bids for recent similar ads within the category. The suggested bid values are refreshed daily.

To understand details about ‘Request Header' or 'Authorization’, please refer to the Authorization Guide

Search an item

Description: You can search for an item which is published on 'samsclub.com' by providing the search string text or item id. The list of items is pulled only from the seller's or supplier's catalog.

End Point: /api/v1/itemSearch

HTTP Method: POST

Body Parameters

Parameter Description Type Required Possible Values
advertiserId The ID of the advertiser whose catalog item is to be retrieved Integer Y Unique numeric identifier
searchText Text for item search. This is used to search the item against both the item name and the entire item description. String N Terms to search an item in catalog
searchItemIds ID linked to the item that the advertiser is selling on the Walmart portal. You can give both the primary variant and variant item id in this field, depending on the requirement Array N String identifier

Note:

  • If searching for a primary variant item, the details will be returned in response. All the variants associated with this primary variant item will be returned to the variantItems array.

  • If searching for a variant item, the corresponding primary variant item details will be returned in response. All the variants associated with the primary variant item will be returned to the variantItems array.

  • You can use either searchText or searchItemIds along with advertiserId to search an item. At least one of these is required. You must not include both.

Sample Request - by searchText

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl --location 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch'
--header 'Authorization: Bearer *********'
--header 'Content-Type: application/json'  
--header 'wm_consumer.id: **************'  
--header 'wm_sec.key_version: 2' 
--header 'wm_sec.auth_signature: **************'  
--header 'wm_qos.correlation_id: 12345'  
--header 'wm_consumer.intimestamp: 1707205605000'   
--data '{ 
      "advertiserId": 1234, 
      "searchText": "Sams Auto" 
  }' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
OkHttpClient client = new OkHttpClient().newBuilder().build(); 
MediaType mediaType = MediaType.parse("application/json"); 
RequestBody body = RequestBody.create(mediaType, 
"{
    "advertiserId": 1234,
    "searchText": "Sams Auto"
}"); 
Request request = new Request.Builder() 
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch") 
.method("POST", body) 
.addHeader("Authorization", "Bearer *********")
.addHeader("Content-Type", "application/json")
.addHeader("wm_consumer.id", "*********") 
.addHeader("wm_sec.key_version", "2") 
.addHeader("wm_sec.auth_signature", "*********") 
.addHeader("wm_qos.correlation_id", "12345") 
.addHeader("wm_consumer.intimestamp", "1707375684000") 
.build(); 
Response response = client.newCall(request).execute(); 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
const axios = require('axios'); 
let data = JSON.stringify({ 
  "advertiserId": 1234, 
  "searchText": "Sams Auto" 
}); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

url: 'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch', 

headers: {  
  'wm_consumer.id': '****************',  
  'wm_sec.key_version': '2',  
  'wm_sec.auth_signature': '****************',  
  'wm_qos.correlation_id': '12345',  
  'wm_consumer.intimestamp': '****************',  
  'Content-Type': 'application/json',  
  'Authorization': 'Bearer ****************' 
}, 
data : data 
}; 
axios.request(config) 
.then((response) => { 
console.log(JSON.stringify(response.data)); 
}) 
.catch((error) => { 
console.log(error); 
});  

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import requests 
import json 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch" 
payload = json.dumps({ 
        "advertiserId": 1234, 
        "searchText": "Sams Auto" 
    }) 
headers = { 
  'Authorization': 'Bearer *********',
  'wm_consumer.id': '***************', 
  'wm_sec.key_version': '2', 
  'wm_sec.auth_signature': '**********', 
  'wm_qos.correlation_id': '12345', 
  'wm_consumer.intimestamp': '1706770087000',
  'Content-Type': 'application/json'  
} 
response = requests.request("POST", url, headers=headers, data=payload) 
print(response.text)

Sample Request - by searchItemIds

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl --location   
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch?auth_token=****************&advertiserId={advertiserId}&campaignId={campaignId}'
--header 'Authorization: Bearer *********' 
--header 'Content-Type: application/json'   
--header 'wm_consumer.id: ****************'  
--header 'wm_sec.key_version: 2' 
--header 'wm_sec.auth_signature: ****************' 
--header 'wm_qos.correlation_id: 1234'  
--header 'wm_consumer.intimestamp: 1702122037000' 
--data '{ 
  "advertiserId": 1234, 
  "searchItemIds": ["1234", "1234"] 
}' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
OkHttpClient client = new OkHttpClient().newBuilder().build(); 
MediaType mediaType = MediaType.parse("application/json"); 
RequestBody body = RequestBody.create(mediaType, 
"{
    "advertiserId": 1234,
    "searchItemIds": ["1234", "1234"]
}"); 
Request request = new Request.Builder() 
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch?auth_token=****************&advertiserId={advertiserId}&campaignId={campaignId}") 
.method("POST", body)
.addHeader("Authorization", "Bearer *********")
.addHeader("Content-Type", "application/json")
.addHeader("wm_consumer.id", "****************") 
.addHeader("wm_sec.key_version", "2") 
.addHeader("wm_sec.auth_signature", "****************") 
.addHeader("wm_qos.correlation_id", "12345") 
.addHeader("wm_consumer.intimestamp", "1702122037000") 
.build(); 
Response response = client.newCall(request).execute(); 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
const axios = require('axios'); 
let data = JSON.stringify({ 
  "advertiserId": 1234, 
  "searchItemIds": ["1234", "1234"] 
}); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

url: 'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch?auth_token=****************&advertiserId={advertiserId}&campaignId={campaignId}'

headers: {  
  'wm_consumer.id': '****************',  
  'wm_sec.key_version': '2',  
  'wm_sec.auth_signature': '****************',  
  'wm_qos.correlation_id': '12345',  
  'wm_consumer.intimestamp': '****************',  
  'Content-Type': 'application/json',  
  'Authorization': 'Bearer ****************' 
}, 
data : data 
}; 
axios.request(config) 
.then((response) => { 
console.log(JSON.stringify(response.data)); 
}) 
.catch((error) => { 
console.log(error); 
});   

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import requests 
import json 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/itemSearch?auth_token=************&advertiserId={advertiserId}&campaignId={campaignId}" 

payload = json.dumps({ 
  "advertiserId": 1234, 
  "searchItemIds": ["1234", "1234"] 
})  
headers = {
  'Authorization': 'Bearer *********', 
  'wm_consumer.id': '************', 
  'wm_sec.key_version': '2', 
  'wm_sec.auth_signature': '**************', 
  'wm_qos.correlation_id': '12345', 
  'wm_consumer.intimestamp': '1706770087000', 
  'Content-Type': 'application/json' 

}

Response

Element Description Type
itemId ID of the primary variant item in search result String
itemName Name of the primary variant item in search result String
itemImageUrl Image URL of the primary variant item String
itemPageUrl Primary variant Item page URL String
suggestedBid Suggested bid (CPC) for the item Double
variantItems An array element to store info of variants associated to the specific primary variant item (whose id is returned in itemId).It stores variant info through following parameters: variantItemId variantItemName variantImageUrl Double

Sample Response - by searchText

[
  {
    "itemId": "44346411",
    "suggestedBid": 0.4,
    "itemName": "TV stand- our TVs are good",
    "variantItems": [
      {
        "variantItemId": "44346411",
        "variantItemName": " TV stand- our TVs are good",
        "variantImageUrl": " https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$"
      },
      {
        "variantItemId": "678903451",
        "variantItemName": " TV stand- our TVs are good ",
        "variantImageUrl": " https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$"
      }
    ],
    "itemImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
    "itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701"
  }
]

Sample Response - by searchItemIds

[
  {
    "itemId": "44346415",
    "suggestedBid": 0.51,
    "itemName": "coffee-cafePress",
    "variantItems": [
      {
        "variantItemId": "44346415",
        "variantItemName": "coffee-cafePress",
        "variantImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$"
      },
      {
        "variantItemId": "44346416",
        "variantItemName": "coffee-cafePress",
        "variantImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$"
      }
    ],
    "itemImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
    "itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701"
  }
]

Note: You will receive information about the primary variant and its variants in the search results. In the event that a primary variant doesn’t have any variant items associated with it, only information belonging to the primary variant is returned.

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • Advertiser Id validation failed
  • At least one of the searchText or searchItemIds is required
  • Both searchText or searchItemIds cannot be present in request
  • Maximum 200 items/keywords can be searched in one api call
  • Channel can either be ONLINE_GROCERY or WALMART
403 Not Found
  • User not Authenticated
  • You do not have access to view this advertiser
404 Not Found Advertiser not found
429 Too Many Requests <Exception Message>
500 Internal Server Error
  • There was an error processing the request
  • Error deserializing : <error message>