Guides
My Account
  1. Assortment Recommendations

Get recommendations API

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

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())

Request sample 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-Items 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

Updated 14 days ago

Did this page help you?