Get recommendations

Market availability: US | MX | CA | CL

Overview

The Get recommendations API provides you with suggestions about what to sell on Walmart Marketplace based on market trends, customer-favorite items, new high demand items over the past 30 days, and gaps in your product availability.

Endpoint

POST https://marketplace.walmartapis.com/v3/growth/assortment/recommendations

Functionality

This call helps you:

To become aware of items in high demand
Identify top products
Learn your customers’ top go get items in the past 30 days
Find recent recommendations
Monitor keyword search trends
Get competitive benchmarking data

Market availability: MX

You can fetch the list of recommendations created for you by using the Get Recommendations API. Use ITEM as the recommendationType.

You can fetch all recommendations created for you or add filterCriteria such as searchText, multiValueFilter, and rangeFilter to fetch a specific set of recommendations. All the filters are connected using the AND operator.

searchText

You can filter using a search term that contains any phrase that could be found anywhere in the recommendations data. The term must not be an empty value. This would filter for the search term present anywhere in the recommendation data.

multiValueFilter

This can be used to filter based on a certain parameter. Currently, the parameters supported are BRAND and CATEGORY. When applying a multiValueFilter, the AND operator is used between the values.

rangeFilter

This can be used to filter based on a range. You must pass a parameter with floor range value, ceiling range value, or both values. Currently, the support parameter value is PRICE for the rangeFilter. The range filter for price is applied on Walmart item prices to fetch the corresponding recommendations.

isTopGoGetItem filter

Filters for Top Go-Get Items—high-demand, customer-favorite items that sellers should prioritize adding to their Walmart catalog. Set to true to return only Top Go-Get Items.

isNewRecommendation filter

Filters for newly added recommendations. These are high-demand, customer-favorite items added to the recommendation set within the past 30 days. Set to true to return only newly added recommendations.

Request samples

All item recommendations

curl --request POST \ --url https://marketplace.walmartapis.com/v3/growth/assortment/recommendations \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "recommendationType": "ITEM", "meta": { "limit": 2 }
}
'

import requests url = "https://marketplace.walmartapis.com/v3/growth/assortment/recommendations" headers = { "accept": "application/json", "content-type": "application/json", # Include your auth + required Walmart headers as applicable in your integration.
} payload = { "recommendationType": "ITEM", "meta": {"limit": 2}
} resp = requests.post(url, headers=headers, json=payload, timeout=30)
resp.raise_for_status()
print(resp.json())

Item recommendations based on filter


curl --request POST \ --url https://marketplace.walmartapis.com/v3/growth/assortment/recommendations \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "recommendationType": "ITEM", "meta": { "limit": 4, "nextCursor": "AoRYPgVANXFt6AeR8QUAAAAAAAAAADkxMDEwMDMwNTZBTkRBTkRCMDg3WVYxOU05" }, "filterCriteria": { "searchText": "and", "multiValueFilter": [ { "parameter": "BRAND", "values": [ "Disney", "NINTENDO" ] }, { "parameter": "CATEGORY", "values": [ "Toys" ] }, { "parameter": "PRODUCT_TYPE", "values": [ "Action Figure Sets", "Power Tool Batteries", "Action Figures" ] } ], "enumFilter": [ { "parameter": "ITEM_AVAILABILITY_STATUS", "values": [ "NEW_TO_WALMART", "EXISTING_IN_WALMART" ] }, { "parameter": "DEMAND_SALES_TRENDS", "values": [ "DEC", "APR", "NOV", "MAR" ] } ], "rangeFilter": [ { "parameter": "PRICE", "from": "1.0", "to": "3.5" } ], "isTopGoGetItem": true, "isNewRecommendation": true }
}
'

import requests url = "https://marketplace.walmartapis.com/v3/growth/assortment/recommendations" headers = { "accept": "application/json", "content-type": "application/json", # Include your auth + required Walmart headers as applicable in your integration.
} payload = { "recommendationType": "ITEM", "meta": {"limit": 2}
} resp = requests.post(url, headers=headers, json=payload, timeout=30)
resp.raise_for_status()
print(resp.json())

Modify your code

1. Add authentication headers

Include required Walmart Marketplace authentication headers such as:

OAuth access token
Consumer ID (if applicable)
Correlation ID

Example additions:

--header 'Authorization: Bearer <ACCESS_TOKEN>' \ --header 'WM_CONSUMER.ID: <CONSUMER_ID>' \ --header 'WM_QOS.CORRELATION_ID: <unique-id>'

import requests url = "https://marketplace.walmartapis.com/v3/growth/assortment/recommendations" headers = { "accept": "application/json", "content-type": "application/json", # Include your auth + required Walmart headers as applicable in your integration.
} payload = { "recommendationType": "ITEM", "meta": {"limit": 2}
} resp = requests.post(url, headers=headers, json=payload, timeout=30)
resp.raise_for_status()
print(resp.json())

2. Control pagination

The response contains:

limit
recordsFetched
totalRecords
nextCursor

To retrieve additional records:

Include the returned nextCursor in the next request (if supported in your implementation)
Adjust meta.limit to control page size

3. Apply filters

To retrieve filtered recommendations:

Add filter parameters in the request body
Narrow results by category, availability status, or business strategy
Use cursor-based pagination to iterate filtered results
Use the filterCriteria parameter to pass in searchText, multiValueFilter, enumFilter, and rangeFilter to generate specific types of recommendations, and boolean filters such as isTopGoGetItem and isNewRecommendation.

4. Parse recommendation data

For each record in payload.records:

Use itemRecommendationUniqueId for tracking
Extract itemDetails including demand, pricing, trends, and competitor data
Prioritize items with:
- isTopGoGetItem = true
- A high rating
- A potentialSalesRank

Response samples

200-All item recommendations

{ "payload": { "recommendationType": "ITEM", "meta": { "totalRecords": 7, "recordsFetched": 2, "limit": 2, "nextCursor": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFmFvVTU3ZXNnUktHbjNxeUJHVHJ6VHcAAAAAAAApuhZqRkg2QURYNFFGR29ZMndCRnp4eEl3" }, "records": [ { "itemRecommendationUniqueId": "552855525", "itemDetails": { "title": "Disney Mirrorverse 5\" Figure WV1 - Sulley", "brand": "Disney", "category": "Toys", "productType": "Action Figures", "gtin": "00787926160345", "upc": "78792616034", "ean": "1234567890123", "itemAvailabilityStatus": "EXISTING_IN_WALMART", "potentialSales": "$0-$10K", "salesInsights": "BEST_SELLER", "potentialSalesRank": 9, "isTopGoGetItem": true, "demandSalesTrends": [ "DEC", "APR", "NOV", "MAR" ], "searchKeywords": [ "MINIVERSE", "MINIVERSE HOLIDAY", "MINVERSE", "SULLEY", "MIRRORVERSE" ], "offerCount": 12, "freeShipping": "YES", "rating": 4.5, "ratingCount": 67, "primaryVariantItemId": "B0CW3VWC3X", "hasVariants": true, "walmart": { "itemId": "552855525", "itemPrice": { "amount": 2.3, "currency": "USD" }, "shippingPrice": { "amount": 0, "currency": "USD" } }, "competitors": [ { "itemId": "B08X954CCW", "url": "www.example.com/dp/B08X954CCW" } ], "restriction": { "isRestricted": false } } }, { "itemRecommendationUniqueId": "B016GASDD8", "itemDetails": { "title": "Animal Crossing Happy Home Designer Amiibo Card Sterling 048/100", "brand": "NINTENDO", "category": "Toys", "productType": "Action Figures", "itemAvailabilityStatus": "NEW_TO_WALMART", "potentialSales": "$0-$10K", "salesInsights": "TRENDING", "potentialSalesRank": 9, "isTopGoGetItem": false, "demandSalesTrends": [ "DEC", "APR", "NOV", "MAR" ], "searchKeywords": [ "raymond amiibo", "raymond amiibo card" ], "offerCount": 10, "freeShipping": "NO", "rating": 4.3, "ratingCount": 16, "hasVariants": false, "competitors": [ { "itemId": "B016GASDD8", "url": "www.example.com/dp/B016GASDD8", "itemPrice": { "amount": 2.95, "currency": "USD" }, "shippingPrice": { "amount": 0.5, "currency": "USD" } } ], "restriction": { "isRestricted": true, "restrictionStatus": "NOT_SUBMITTED" } } } ] }
}

200 - Item Recommendations Based On Filter

{ "payload": { "recommendationType": "ITEM", "meta": { "totalRecords": 7, "recordsFetched": 3, "limit": 3, "nextCursor": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFmFvVTU3ZXNnUktHbjNxeUJHVHJ6VHcAAAAAAAApuhZqRkg2QURYNFFGR29ZMndCRnp4eEl3" }, "records": [ { "itemRecommendationUniqueId": "552855525", "itemDetails": { "title": "Disney Mirrorverse 5\" Figure WV1 - Sulley", "brand": "Disney", "category": "Toys", "productType": "Action Figures", "gtin": "00787926160345", "upc": "78792616034", "ean": "1234567890123", "itemAvailabilityStatus": "EXISTING_IN_WALMART", "potentialSales": "$0-$10K", "salesInsights": "HIGHLY_SEARCHED", "potentialSalesRank": 9, "isTopGoGetItem": true, "demandSalesTrends": [ "DEC", "APR", "NOV", "MAR" ], "searchKeywords": [ "MINIVERSE", "MINIVERSE HOLIDAY", "MINVERSE", "SULLEY", "MIRRORVERSE" ], "offerCount": 10, "freeShipping": "YES", "rating": 4.7, "ratingCount": 71, "primaryVariantItemId": "B0CW3VWC3X", "hasVariants": true, "walmart": { "itemId": "552855525", "itemPrice": { "amount": 2.3, "currency": "USD" }, "shippingPrice": { "amount": 0, "currency": "USD" } }, "competitors": [ { "itemId": "B08X954CCW", "url": "www.example.com/dp/B08X954CCW" } ], "restriction": { "isRestricted": true, "restrictionStatus": "UNDER_REVIEW" } } }, { "itemRecommendationUniqueId": "B016GASDD8", "itemDetails": { "title": "Animal Crossing Happy Home Designer Amiibo Card Sterling 048/100", "brand": "NINTENDO", "category": "Toys", "productType": "Action Figures", "itemAvailabilityStatus": "NEW_TO_WALMART", "potentialSales": "$0-$10K", "salesInsights": "BEST_SELLER", "potentialSalesRank": 9, "isTopGoGetItem": false, "demandSalesTrends": [ "DEC", "APR", "NOV", "MAR" ], "searchKeywords": [ "raymond amiibo", "raymond amiibo card" ], "offerCount": 10, "freeShipping": "NO", "rating": 3.9, "ratingCount": 23, "primaryVariantItemId": "B0CW3VWC3X", "hasVariants": false, "competitors": [ { "itemId": "B016GASDD8", "url": "www.example.com/dp/B016GASDD8", "itemPrice": { "amount": 2.95, "currency": "USD" }, "shippingPrice": { "amount": 0.75, "currency": "USD" } } ], "restriction": { "isRestricted": true, "restrictionStatus": "APPROVED" } } }, { "itemRecommendationUniqueId": "B0DG9FQKR2", "itemDetails": { "title": "Mermaid Tail Blanket for Kids, Soft Crochet Sleeping Bag", "brand": "Generic", "category": "Toys", "productType": "Action Figures", "itemAvailabilityStatus": "NEW_TO_WALMART", "potentialSales": "$0-$10K", "salesInsights": "TRENDING", "potentialSalesRank": 9, "isTopGoGetItem": false, "demandSalesTrends": [ "DEC", "APR", "NOV", "MAR" ], "searchKeywords": [ "mermaid blanket", "mermaid tail" ], "offerCount": 6, "freeShipping": "YES", "rating": 4.2, "ratingCount": 34, "primaryVariantItemId": "B0DG9FQKR2", "hasVariants": false, "competitors": [ { "itemId": "B0DG9FQKR2", "url": "www.example.com/dp/B0DG9FQKR2", "itemPrice": { "amount": 19.99, "currency": "USD" }, "shippingPrice": { "amount": 0, "currency": "USD" } } ], "restriction": { "isRestricted": true, "restrictionStatus": "DENIED_CAN_REAPPLY" } } } ] }
}

400 - Required Header Missing Or Blank (All 5 Operations)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST", "description": "Missing or invalid header", "severity": "ERROR", "category": "REQUEST" } ]
}

400 - Unsupported RecommendationType (POST/Recommendations Only)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_CONTENT", "description": "Unsupported recommendation type", "severity": "ERROR", "category": "SYSTEM" } ]
}

400 - Field-Level Validation Failure (POST/Recommendations)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_CONTENT", "field": "meta.limit", "description": "meta.limit value should be minimum 1 and maximum 200", "severity": "ERROR", "category": "DATA" } ]
}

400 - Field-Level Validation Failure (POST/Categorization/Counts)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_CONTENT", "field": "categorizationType", "description": "The categorizationType parameter can neither be NULL nor blank.", "severity": "ERROR", "category": "DATA" } ]
}

400 - Field-Level Validation Failure (PUT /Rejections)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_CONTENT", "field": "rejectionCodes", "description": "The rejectionCodes parameter must not be NULL.", "severity": "ERROR", "category": "DATA" } ]
}

400 - Required Query Parameter Missing (GET/Variants)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_PARAM", "field": "primaryVariantId", "description": "The primary variant item ID cannot be null/blank.", "severity": "ERROR", "category": "REQUEST" } ]
}

400 - Required Query Parameter Missing (GET/Trends)

{ "payload": null, "errors": [ { "code": "INVALID_REQUEST_PARAM", "field": "recommendationUniqueId", "description": "The recommendation unique ID cannot be null/blank.", "severity": "ERROR", "category": "REQUEST" } ]
}

403

{ "payload": null, "errors": [ { "code": "ACCESS_DENIED", "description": "The caller is not authorized to access this resource", "severity": "ERROR", "category": "REQUEST" } ]
}

500

{ "payload": null, "errors": [ { "code": "SYSTEM_ERROR", "description": "Something went wrong while processing request at server", "severity": "ERROR", "category": "APPLICATION" } ]
}

Result

The Get recommendations API provides curated recommendations to grow your assortment.
Responses provide:
- A paginated list of recommended items
- Unique recommendation IDs
- Product-level details (brand, category, GTIN, trends)
- Sales potential indicators
- Competitor data
- Walmart catalog availability
- Variant indicators
- Cursor token for pagination

Next steps

Get recommendations API: Makes suggestions about what to sell on Walmart Marketplace based on market trends, customer-favorite items, high demand items over the past 30 days, and gaps in your product availability.
- Get recommendations API Guide
- Get recommendations API Reference Guide
Get variants API: Lists customer favorite preferences such as size, color, or material.
- Get variants API Guide
- Get variants API Reference Guide
Get recommendation trends API: Provides data trends about your assortment on Walmart, such as price and demand trends, so you can respond quickly and maintain a competitive edge.
- Get recommendation trends API Guide
- Get recommendation trends API Reference Guide
Get categorization API: Provides a list of brands and categories for every recommended item, then a secondary sort by alphabetical order. You can use BRAND or CATEGORY for categorizationType.
- Get categorization API Guide
- Get categorization API Reference Guide
Reject recommendations API: Lets you reject items Walmart recommends. If you reject a recommended item, you won’t see it again.
- Reject recommendations API Guide
- Reject recommendations API Reference Guide

Updated 11 days ago

Did this page help you?