Guides
My Account

Get top recommended items

The Catalog Item Recommendation API returns up to 200 top recommended items from your catalog that are eligible for a campaign. Pagination and result customization are not supported.

How it works

  • On each call, the service ranks your eligible catalog and returns the top 200 recommendations (if at least 200 are eligible).
  • Items that are part of any active campaign are automatically excluded from the response. For example: If a seller has 500,000 eligible items, the API returns the top 200 valid recommendations in one response.

Response behavior

  • Results are returned in a single response. Repeating the request will return the same ranked set unless your catalog or campaign data changes.
  • Only items not currently included in active campaigns are returned.
  • When fewer than 200 items are eligible, the response contains as many as available (up to 200).

Additionally, you can use the Catalog Search API to assist with your queries.

Throttling

This API endpoint is throttled—if you submit too many feeds too quickly, you might hit Walmart’s rate limits and receive HTTP 429 responses. To learn more about throttling, refer to the Marketplace throttling documentation.

Endpoint

GET /v3/advertising/sem/items/recommendation

Sample request

Use this example as a starting point, then modify it with your actual values and any additional parameters described in the API reference.

curl --location 'https://marketplace.walmartapis.com/v3/advertising/sem/items/recommendations?limit=10' \
--header 'WM_SVC.NAME: Search Engine Marketing' \
--header 'WM_QOS.CORRELATION_ID: 09fa4596-d9fb-4258-810b-460dc027b7f7' \
--header 'WM_SEC.ACCESS_TOKEN: **********'

import requests url = "https://marketplace.walmartapis.com/v3/advertising/sem/items/recommendations?limit=10" headers = { "WM_SVC.NAME": "Search Engine Marketing", "WM_QOS.CORRELATION_ID": "09fa4596-d9fb-4258-810b-460dc027b7f7", "WM_SEC.ACCESS_TOKEN": "**********"
} response = requests.get(url, headers=headers) print(response.text)

Modify your code

  1. If needed, update the limit query parameter value of 10 in the URL to the desired number of recommendations to be returned. This value cannot exceed 200.
  2. Use your unique WM_QOS.CORRELATION_ID for each request.
  3. Use your unique WM_SEC.ACCESS_TOKEN obtained from the Token API.

Sample response

{ "pagination": { "pageNo": 0, "pageSize": 10, "totalCount": 3, "totalPages": 1 }, "data": [ { "itemId": "5014488974", "sku": "sku_07144442400738_test", "productId": "1A2B3C4D5E", "productName": "Wireless Bluetooth Headphones", "categoryName": "Electronics", "productUrl": "/ip/Headphones/5014488974", "productImageUrl": "https://i5-qa.walmartimages.com/asr/dffe200d-117d-4804-a4de-aebbdbe7a616.ccd4b68eb51087086daf6c75197b214b.avif", "recommendationType": "HIGHLY_RECOMMENDED" }, { "itemId": "5014389813", "sku": "sku_00993001888299_test", "productId": "1YO2HKFIAB1E", "productName": "Womens Square Neck Ribbed Sweater Dress", "categoryName": "Clothing", "productUrl": "/ip/Sweater/5014389813", "productImageUrl": "https://i5-qa.walmartimages.com/asr/cc211564-bf4c-4810-8474-3b192a1c8631.e87331cdd32950f6f83a239743ea9816.jpeg", "recommendationType": "HIGHLY_RECOMMENDED" }, { "itemId": "5014389838", "sku": "sku_07148487515983_test", "productId": "2CZOV9ZBND06", "productName": "Low-Fat Milk", "categoryName": "Food & Beverage", "productUrl": "/ip/Milk/5014389838", "productImageUrl": "https://i5-qa.walmartimages.com/asr/030d9eed-3b2c-4d5f-baa3-55c82fa36e0a.5b1cc2147571bae5b3c62016c6220309.jpeg", "recommendationType": "STANDARD_RECOMMENDED" } ]
}

Result

If successful, the API response returns an HTTP status: 200 OK with a JSON payload containing a list of items and their recommendation type.

Updated 5 days ago