Catalog Item Search

These APIs provides capability to search advertisers’ items that are part of retail catalog published on Walmart.com.

Catalog Item API endpoint limitations:
Item search operation will yield a maximum of 200 primary variant items (formerly known as base items) for an advertiser. There is no limit on number of variant items that are returned for a primary variant item.

Note: 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.

Description: You can search an item by providing search string text or item id. List of items is pulled only from seller/supplier catalog.

URL: POST /api/v1/itemSearch

Query Parameters

Parameter	Description	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
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 item name and entire item description.	string	N	Terms to search an item in catalog
searchItemIds	ID linked to the item that advertiser is selling on the Walmart portal. You can give both primary variant and variant item id in this field depending upon the requirement Note: 1. 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 in the variantItems array. 2. If searching for a variant item, corresponding primary variant item details will be returned in response. All the variants associated with the primary variant item will be returned in the variantItems array.	array	N	String identifier

Note: 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.

Headers

Header Name	Description	Required	Values
WM_CONSUMER.ID	We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATURE	Auth signature as an API key	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp	Y	Use the signature generator code (Getting Started Guide) to generate this value

Sample Request when Search for Item by searchText:

curl --location --request POST 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/itemSearch?auth_token=1234' \
--header 'accept: application/json' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--header 'Content-Type: application/json' \
--data-raw '{ "advertiserId": 5678,  
"searchText": "tv" 
}'

Sample Request when Search for Item by searchItemIds:

curl --location --request POST 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/itemSearch?auth_token=1234' \
--header 'accept: application/json' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--header 'Content-Type: application/json' \
--data-raw ' 
{ "advertiserId": 5678,  
"searchItemIds": ["44346415", "44346416"] 
} '

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: 1. variantItemId 2. variantItemName 3. variantImageUrl	array

Sample Response when Search for Item 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://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474-730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff"
      },
      {
        "variantItemId": "678903451",
        "variantItemName": " TV stand- our TVs are good ",
        "variantImageUrl": " https://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474-730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff"
      }
    ],
    "itemImageUrl": "https://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474- 730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
    "itemPageUrl": "https://www.walmart.com/ipseort/44346411"
  }
]

Sample Response when Search for Item by searchItemIds:

[
  {
    "itemId": "44346415",
    "suggestedBid": 0.51,
    "itemName": "coffee-cafePress",
    "variantItems": [
      {
        "variantItemId": "44346415",
        "variantItemName": "coffee-cafePress",
        "variantImageUrl": "https://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474-730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff"
      },
      {
        "variantItemId": "44346416",
        "variantItemName": "coffee-cafePress",
        "variantImageUrl": "https://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474-730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff"
      }
    ],
    "itemImageUrl": "https://i5.walmartimages.com/asr/905eb620-b036-48e9-b8df-8a00257efca0_1.cd6ce64707093979d61b67379b985e1d.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
    "itemPageUrl": "https://www.walmart.com/ip/562728956"
  }
]

Note: You will receive information of primary variant and its variants in the search results. In case a primary variant doesn’t have any variant item associated, only information belonging to primary variant is returned.

There is a rate limit in place on the allowed number of API operations per hour.

Operations per hour are computed as the sum of number of changes requested across all API requests during the hour.

For example, 5 keyword bid changes, creation of an ad group, adding an item, and a snapshot report request in any given hour, would be counted as 8 operations.

You will receive an HTTP 429 status error code and an error message about rule enforced in case of breaking ops limit.

To learn more about current applicable limits specific to your integration, please reach out to the API Partner Enablement team.