Assortment recommendations empower sellers understand and identify the customer demand in Walmart & market by curating personalised seller recommendations by leveraging demand signals such as Internal and external search, Best Sellers, Trending items, and more.
openapi: 3.0.1
info:
title: Walmart Assortment Recommendations Overview
description: "Assortment recommendations empower sellers understand customer demand in Walmart & market by curating personalised seller recommendations by leveraging demand signals such as \n* Internal and external search \n* Best Sellers\n* Trending items, and more.\n\nAssortment Recommendations API can be used to viewed, bulk download, filtered, rejected and shortlist the recommendations. These shortlisted items can be set up using the [Item Setup API](https://developer.walmart.com/api/us/mp/items).\nSellers need to provide API access key on [developer portal](https://developer.walmart.com/account/generateKey) for ‘Analytics & Growth’ to solution providers and channel partners to be able to access Assortment Growth APIs."
servers:
- url: https://marketplace.walmartapis.com
description: Production URL
- url: https://sandbox.walmartapis.com
description: Sandbox URL
security:
- basicScheme: []
paths:
"/v3/growth/assortment/recommendations":
post:
tags:
- Assortment Recommendations
summary: Walmart Get Recommendations
description: "You can fetch the list of recommendations that are recommended for you. \n \nUsing ITEM as a recommendationType,\n* You can get the list of ITEM recommendations. You can apply filters to fetch selective item recommendations. \n \n\n"
externalDocs:
description: View Guide
url: "/doc/us/us-mp/us-mp-assortmentrecommendations/#12957"
operationId: getAssortmentRecommendations
parameters:
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
- in: header
name: Accept
description: 'Only supported Media Type : application/json'
required: true
schema:
type: string
example: application/json
requestBody:
description: Request payload
content:
application/json:
schema:
required:
- recommendationType
type: object
properties:
recommendationType:
type: string
description: |-
| Attribute | Description | Data Type |
| --- | ----------- | ------- |
| ITEM | To get list of recommended items | string |
enum:
- ITEM
meta:
type: object
properties:
limit:
maximum: 200
minimum: 1
type: integer
description: Number of records expected in the request
format: int32
default: 200
nextCursor:
type: string
description: Used for pagination when more than 200 records are retrieved. The nextCursor value of the response includes a marker which needs to be passed in next call which retrieves the next page of results.
description: Meta information for the request.
filterCriteria:
type: object
properties:
searchText:
minLength: 3
type: string
description: 'To filter with a search text having a word that can be part of the recommended data. '
multiValueFilter:
type: array
description: "Filters based on multiple values associated with a specific parameter. \nNo parameter should be repeated."
items:
required:
- parameter
type: object
properties:
parameter:
type: string
description: |-
| Attribute | Description | Data Type |
| --- | ----------- | ------- |
| BRAND | To filter based on list of brands which are associated with the assortment recommendations | string |
| CATEGORY | To filter based on list of categories which are associated with the assortment recommendations | string |
enum:
- BRAND
- CATEGORY
values:
type: array
description: A list of values corresponds to the parameter in the filter. The values in the list should not be null or blank. Maximum size of the list should be 7.
items:
type: string
description: A list of values corresponds to the parameter in the filter. The values in the list should not be null or blank. Maximum size of the list should be 7.
description: "Filters based on multiple values associated with a specific parameter. \nNo parameter should be repeated."
enumFilter:
type: array
description: "Filter based on preset parameters and their associated values is possible with EnumFilter. \nNo parameter should be repeated."
items:
type: object
properties:
parameter:
type: string
description: "To apply an enum filter based on the predefined parameter. \n\n| Attribute | Description | Data Type |\n| --- | ----------- | ------- |\n| ITEM_AVAILABILITY_STATUS | To filter based on whether the items which are new to Walmart or existing in Walmart. | string |\n| SHOPPING_TRENDS | Indicates the demand types identified in the market for an item. An item can have more than one value for this parameter. | string |"
enum:
- ITEM_AVAILABILITY_STATUS
values:
type: array
description: "Values correspond to the parameter for applying filter on the response. The data in values[] are predefined. OR operator is used between the values. \n\n| Attribute | Associated parameter of enumFilter | Description | Data Type |\n| --- | ----------- | ----------- | ------- |\n| EXISTING_IN_WALMART | ITEM_AVAILABILITY_STATUS | To filters based on the items which are existing in Walmart. | string |\n| NEW_TO_WALMART | ITEM_AVAILABILITY_STATUS | To filters based on the items which are new to Walmart. | string |\n| MOST_SEARCHED_FOR | SHOPPING_TRENDS | Item is most searched for in the market. | string |\n| BEST_SELLERS | SHOPPING_TRENDS | Item is best seller in the market. | string |\n| DEAL_ITEMS | SHOPPING_TRENDS | Item is in demand and is a part of deals in the other marketplaces. | string |\n"
items:
type: string
description: "Values correspond to the parameter for applying filter on the response. The data in values[] are predefined. OR operator is used between the values. \n\n| Attribute | Associated parameter of enumFilter | Description | Data Type |\n| --- | ----------- | ----------- | ------- |\n| EXISTING_IN_WALMART | ITEM_AVAILABILITY_STATUS | To filters based on the items which are existing in Walmart. | string |\n| NEW_TO_WALMART | ITEM_AVAILABILITY_STATUS | To filters based on the items which are new to Walmart. | string |\n| MOST_SEARCHED_FOR | SHOPPING_TRENDS | Item is most searched for in the market. | string |\n| BEST_SELLERS | SHOPPING_TRENDS | Item is best seller in the market. | string |\n| DEAL_ITEMS | SHOPPING_TRENDS | Item is in demand and is a part of deals in the other marketplaces. | string |\n"
enum:
- EXISTING_IN_WALMART
- NEW_TO_WALMART
- MOST_SEARCHED_FOR
- BEST_SELLERS
- DEAL_ITEMS
enum:
- EXISTING_IN_WALMART
- NEW_TO_WALMART
- MOST_SEARCHED_FOR
- BEST_SELLERS
- DEAL_ITEMS
description: "Filter based on preset parameters and their associated values is possible with EnumFilter. \nNo parameter should be repeated."
rangeFilter:
type: array
description: "Filter based on a range with RangeFilter. You must also pass a parameter along with any of the beginning or the ending points or both. \nNo parameter should be repeated."
items:
type: object
properties:
parameter:
type: string
description: "To apply a range filter based on the predefined parameter. \n\n| Attribute | Description | Data Type |\n| --- | ----------- | ------- |\n| PRICE | To filter based on the price. | string |"
enum:
- PRICE
from:
type: string
description: Filter range start
to:
type: string
description: Filter range end
description: "Filter based on a range with RangeFilter. You must also pass a parameter along with any of the beginning or the ending points or both. \nNo parameter should be repeated."
description: Different type of filters can be passed in this object.
examples:
All item recommendations:
value:
recommendationType: ITEM
meta:
limit: 2
Item recommendations based on filter:
value:
recommendationType: ITEM
meta:
limit: 4
nextCursor: AoRYPgVANXFt6AeR8QUAAAAAAAAAADkxMDEwMDMwNTZBTkRBTkRCMDg3WVYxOU05
filterCriteria:
searchText: and
multiValueFilter:
- parameter: BRAND
values:
- Florida Atlantic University
- maximalpower
- delsit
- parameter: CATEGORY
values:
- TOPS SPORTSWEAR ECOMM MENS
- TODDLER FURNITURE
- FLOORCARE
enumFilter:
- parameter: ITEM_AVAILABILITY_STATUS
values:
- NEW_TO_WALMART
- EXISTING_IN_WALMART
- parameter: SHOPPING_TRENDS
values:
- MOST_SEARCHED_FOR
- BEST_SELLERS
- DEAL_ITEMS
rangeFilter:
- parameter: PRICE
from: '10.0'
to: '80.5'
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
payload:
required:
- recommendationType
type: object
properties:
recommendationType:
type: string
description: |-
| Attribute | Description | Data Type |
| --- | ----------- | ------- |
| ITEM | To get list of recommended items | string |
enum:
- ITEM
meta:
type: object
properties:
totalRecords:
type: integer
description: The total number of records are present for the requested categorization type along with filters.
format: int32
recordsFetched:
type: integer
description: The number of records fetched in the response.
format: int32
limit:
maximum: 200
minimum: 1
type: integer
description: Number of records expected in the request
format: int32
default: 200
nextCursor:
type: string
description: The string returned from the initial API call to indicate nextCursor. Specify nextCursor value to retrieve the next set of records.
description: Meta information for the response.
records:
type: array
description: Information related to the item recommendations.
items:
type: object
properties:
itemRecommendationUniqueId:
type: string
description: Unique identifier for the recommended item.
itemDetails:
type: object
properties:
title:
type: string
description: Title of the recommended item
brand:
type: string
description: Brand of the recommended item
category:
type: string
description: Category of the recommended item
gtin:
type: string
description: GTIN of the recommended item
upc:
type: string
description: UPC of the recommended item
isbn:
type: string
description: ISBN of the recommended item
ean:
type: string
description: EAN of the recommended item
itemAvailabilityStatus:
type: string
description: "Item availability status of the recommended item. \n\n| Attribute | Description | Data Type |\n| --- | ----------- | ------- |\n| EXISTING_IN_WALMART | Indicates that item is existing in Walmart. | string |\n| NEW_TO_WALMART | Indicates that item is new to Walmart. | string |"
enum:
- EXISTING_IN_WALMART
- NEW_TO_WALMART
potentialSales:
type: string
description: "Indicates the potential revenue the recommended item can bring in over a year. \nThis field does not promise the numbers indicated."
shoppingTrends:
type: array
description: "Indicates the demand type for an item. \n\n| Attribute | Description | Data Type |\n| --- | ----------- | ------- |\n| MOST_SEARCHED_FOR | Item is most searched for in the market. | string |\n| BEST_SELLERS | Item is best seller in the market. | string |\n| DEAL_ITEMS | Item is in demand and is a part of deals in the other marketplaces. | string |"
items:
type: string
description: "Indicates the demand type for an item. \n\n| Attribute | Description | Data Type |\n| --- | ----------- | ------- |\n| MOST_SEARCHED_FOR | Item is most searched for in the market. | string |\n| BEST_SELLERS | Item is best seller in the market. | string |\n| DEAL_ITEMS | Item is in demand and is a part of deals in the other marketplaces. | string |"
enum:
- MOST_SEARCHED_FOR
- BEST_SELLERS
- DEAL_ITEMS
enum:
- MOST_SEARCHED_FOR
- BEST_SELLERS
- DEAL_ITEMS
walmart:
type: object
properties:
itemId:
type: string
description: Walmart item id.
url:
type: string
description: Walmart item url.
wfsIndicator:
type: boolean
description: Walmart fulfilment service indicator.
itemPrice:
type: object
properties:
amount:
type: number
description: 'The numerical amount of the price. Example: 9.99'
format: double
currency:
type: string
description: Currency associated with the price of the item recommendation.
description: Competitor's item shipping price details of the item recommendation.
shippingPrice:
type: object
properties:
amount:
type: number
description: 'The numerical amount of the price. Example: 9.99'
format: double
currency:
type: string
description: Currency associated with the price of the item recommendation.
description: Competitor's item shipping price details of the item recommendation.
description: Walmart's item information
competitors:
type: array
description: Competitor's item information
items:
type: object
properties:
itemId:
type: string
description: Competitor item id.
url:
type: string
description: Competitor item url.
itemPrice:
type: object
properties:
amount:
type: number
description: 'The numerical amount of the price. Example: 9.99'
format: double
currency:
type: string
description: Currency associated with the price of the item recommendation.
description: Competitor's item shipping price details of the item recommendation.
shippingPrice:
type: object
properties:
amount:
type: number
description: 'The numerical amount of the price. Example: 9.99'
format: double
currency:
type: string
description: Currency associated with the price of the item recommendation.
description: Competitor's item shipping price details of the item recommendation.
description: Competitor's item information
description: Details of the recommended item.
description: Information related to the item recommendations.
description: Payload in the response having the details about the item recommendations.
examples:
All item recommendations:
value:
payload:
recommendationType: ITEM
meta:
totalRecords: 45747
recordsFetched: 2
limit: 2
nextCursor: AoRYPgVAkFauFHrhSAU/5cbOnJbgPT04MDZBTkQ4Mjk4MTIyMTMxQU5EQjAxTkNYSkJQOQ==
records:
- itemRecommendationUniqueId: 806AND8707224727ANDB06XCG9QPJ
itemDetails:
title: Allurez Heart and Diamond Initials Lariat Pendant Y-Necklace in 14k Rose Gold
brand: Allurez
category: DIAMOND JEWELRY ECOMM WOMENS
gtin: '06651291438962'
upc: '0665129143896'
itemAvailabilityStatus: EXISTING_IN_WALMART
potentialSales: "$100K+"
shoppingTrends:
- MOST_SEARCHED_FOR
- BEST_SELLERS
walmart:
itemId: '707224727'
url: www.walmart.com/ip/707224727
itemPrice:
amount: 299.99
currency: USD
shippingPrice:
amount: 0
currency: USD
competitors:
- itemId: B06XCG9QPJ
url: www.amazon.com/dp/B06XCG9QPJ
itemPrice:
amount: 1192
currency: USD
shippingPrice:
amount: 0
currency: USD
- itemRecommendationUniqueId: 806AND8298122131ANDB01NCXJBP9
itemDetails:
title: Three-Stone Leverback Diamond Earrings 14k Yellow Gold (0.50ct)
brand: Allurez
category: DIAMOND JEWELRY ECOMM WOMENS
gtin: '04692981221312'
upc: '0469298122131'
itemAvailabilityStatus: EXISTING_IN_WALMART
potentialSales: "$50K-$100K"
shoppingTrends:
- BEST_SELLERS
walmart:
itemId: '298122131'
url: www.walmart.com/ip/298122131
itemPrice:
amount: 777
currency: USD
shippingPrice:
amount: 0
currency: USD
competitors:
- itemId: B01NCXJBP9
url: www.amazon.com/dp/B01NCXJBP9
itemPrice:
amount: 670
currency: USD
shippingPrice:
amount: 0
currency: USD
Item recommendations based on filter:
value:
payload:
recommendationType: ITEM
meta:
totalRecords: 45747
recordsFetched: 2
limit: 2
nextCursor: AoRYPgVAkFauFHrhSAU/5cbOnJbgPT04MDZBTkQ4Mjk4MTIyMTMxQU5EQjAxTkNYSkJQOQ==
records:
- itemRecommendationUniqueId: acca7a9b-07dd-4ba3-970a-6a404e9e8240
itemDetails:
title: MaximalPower Replacement Vacuum Filter For EUREKA DCF-4 DCF-18 Washable and Reusable Replaces Eureka GE DCF1 DCF4 DCF18 28608-1 28608B-1 62132 63073 61770 3690 18505 - 2 PACK
brand: maximalpower
category: FLOORCARE
gtin: '00797518364449'
upc: '0072819436444'
ean: '51985410715'
itemAvailabilityStatus: EXISTING_IN_WALMART
potentialSales: "$100K+"
shoppingTrends:
- MOST_SEARCHED_FOR
- BEST_SELLERS
walmart:
itemId: '810058003'
url: www.walmart.com/ip/810058003
itemPrice:
amount: 28.49
currency: USD
shippingPrice:
amount: 0
currency: USD
competitors:
- itemId: B075LXQF2B
url: www.amazon.com/dp/B075LXQF2B
itemPrice:
amount: 15.97
currency: USD
shippingPrice:
amount: 0
currency: USD
- itemRecommendationUniqueId: 660c6344-0106-4412-a993-9ffc93937f9c
itemDetails:
title: Florida Atlantic University Official State Shape and Unisex Adult Tank Top
brand: Florida Atlantic University
category: TOPS SPORTSWEAR ECOMM MENS
itemAvailabilityStatus: NEW_TO_WALMART
potentialSales: "$50K-$100K"
shoppingTrends:
- BEST_SELLERS
competitors:
- itemId: B0800Y7PSW
url: www.amazon.com/dp/B0800Y7PSW
itemPrice:
amount: 19.99
currency: USD
shippingPrice:
amount: 0
currency: USD
"/v3/growth/assortment/recommendations/categorization/counts":
post:
tags:
- Assortment Recommendations
summary: Walmart Get Categorization
description: "You can get the list of brands or categories associated with the items recommendations that are recommended for you.\n \nUsing BRAND as a categorizationType\n* You can get the list of brands sorted by the number of item recommendations associated with it. This is then sorted in lexicographic order of brand name. \n \n\nUsing CATEGORY as a categorizationType\n* You can get the list of categories sorted by the number of item recommendations associated with it. This is then sorted in lexicographic order of category name. \n \n\n"
externalDocs:
description: View Guide
url: "/doc/us/us-mp/us-mp-assortmentrecommendations/#12960"
operationId: getCategorizationDetailsOfAssortmentRecommendations
parameters:
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
- in: header
name: Accept
description: 'Only supported Media Type : application/json'
required: true
schema:
type: string
example: application/json
requestBody:
description: Request payload
content:
application/json:
schema:
required:
- categorizationType
type: object
properties:
categorizationType:
type: string
description: |-
| Attribute | Description | Data Type |
| --- | ----------- | ------- |
| BRAND | To get list of brands which are associated with the assortment
# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/walmart/refs/heads/main/openapi/walmart-marketplace-recommendations-openapi-original.yml