Guides
My Account
  1. Assortment Recommendations
  2. Assortment recommendations overview

Get categorization API

Market availability: US only

Overview

The 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.

Endpoint

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

Functionality

This API helps you:

  • Build search filters to find different aspects and qualities
  • Refine filter recommendations
  • Navigate large recommendation datasets

Market availability: MX

You can fetch the list of brands and categories of the item recommendations that are recommended for you by using the Get Categorization API. You can currently use BRAND or CATEGORY as the categorization Type.

BRAND as a type of categorization
  • Here 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.
  • You can also add filterCriteria such as searchText and multiValueFilter to get a specific set of results.
  • You will be able to pull all records in one response.
CATEGORY as a type of categorization
  • Here you can get the list of categories.
  • You can add filterCriteria like searchText and multiValueFilter to get specific set of results.
  • You will be able to pull all records in one response.

Request sample All brands associated with the item recommendations

curl --request POST \ --url https://marketplace.walmartapis.com/v3/growth/assortment/recommendations/categorization/counts \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "categorizationType": "BRAND", "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 Brands based on filter associated with the item recommendations

curl --request POST \ --url https://marketplace.walmartapis.com/v3/growth/assortment/recommendations/categorization/counts \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "categorizationType": "BRAND", "meta": { "limit": 2, "nextCursor": "categorizationType=BRAND&limit=2&offset=2" }, "filterCriteria": { "searchText": "and", "multiValueFilter": [ { "parameter": "CATEGORY", "values": [ "FINE GEMSTONE JEWELRY ECOMM WOMENS", "FASHION JEWELRY ECOMM WOMENS" ] } ] }
}
'

Request sample All categories associated with the item recommendations

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

Request sample Categories based on filter associated with the item recommendations

curl --request POST \ --url https://marketplace.walmartapis.com/v3/growth/assortment/recommendations/categorization/counts \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "categorizationType": "CATEGORY", "meta": { "limit": 2, "nextCursor": "categorizationType=CATEGORY&limit=2&offset=2" }, "filterCriteria": { "searchText": "ecomm", "multiValueFilter": [ { "parameter": "BRAND", "values": [ "Swarovsk and Co.", "Kate Spade and Co." ] } ] }
}
'
import requests url = "https://marketplace.walmartapis.com/v3/growth/assortment/recommendations" headers = { "WM_GLOBAL_VERSION": "3.1", "WM_MARKET": "us", "accept": "application/json", "content-type": "application/json", # Include your auth + required Walmart headers as applicable in your integration.
} payload = { "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": "SHOPPING_TRENDS", "values": ["MOST_SEARCHED_FOR", "BEST_SELLERS", "DEAL_ITEMS"]}, {"parameter": "DEMAND_SALES_TRENDS", "values": ["DEC", "APR", "NOV", "MAR"]}, ], "rangeFilter": [ {"parameter": "PRICE", "from": "1.0", "to": "3.5"} ], "isTopGoGetItem": True, "isNewRecommendation": True, },
} 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 Marketplace authentication headers:

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

2. Apply filtering logic

You can refine results using:

  • searchText: Keyword-based filtering

Response sample 200 – All brands associated with the item recommendations

{ "payload": { "categorizationType": "BRAND", "meta": { "totalRecords": 4, "recordsFetched": 2, "limit": 2, "nextCursor": "categorizationType=BRAND&limit=2&offset=2" }, "records": [ { "name": "Swarovsk and Co.", "numberOfItemRecommendations": -1 }, { "name": "Kate Spade and Co.", "numberOfItemRecommendations": -1 } ] }
}

Response sample 200 – Brands based on filter associated with the item recommendations

{ "payload": { "categorizationType": "BRAND", "meta": { "totalRecords": 10, "recordsFetched": 2, "limit": 2, "nextCursor": "categorizationType=BRAND&limit=2&offset=2" }, "records": [ { "name": "Swarovsk and Co.", "numberOfItemRecommendations": -1 }, { "name": "Kate Spade and Co.", "numberOfItemRecommendations": -1 } ] }
}

Response sample 200 – All categories associated with the item recommendations

{ "payload": { "categorizationType": "CATEGORY", "meta": { "totalRecords": 18, "recordsFetched": 2, "limit": 2, "nextCursor": "categorizationType=CATEGORY&limit=2&offset=4" }, "records": [ { "name": "FINE GEMSTONE JEWELRY ECOMM WOMENS", "numberOfItemRecommendations": -1 }, { "name": "FASHION JEWELRY ECOMM WOMENS", "numberOfItemRecommendations": -1 } ] }
}

Response sample 200 – Categories based on filter associated with the item recommendations

{ "payload": { "categorizationType": "CATEGORY", "meta": { "totalRecords": 20, "recordsFetched": 2, "limit": 2, "nextCursor": "categorizationType=CATEGORY&limit=2&offset=4" }, "records": [ { "name": "FINE GEMSTONE JEWELRY ECOMM WOMENS", "numberOfItemRecommendations": -1 }, { "name": "FASHION JEWELRY ECOMM WOMENS", "numberOfItemRecommendations": -1 } ] }
}

Result

  • This API returns categorizations by BRAND or CATEGORY.
  • Each record contains:
    • name:BRANDorCATEGORY name
    • numberOfItemRecommendations The number of recommendations per item
  • Pagination is supported using nextCursor.
  • Filtering enables dynamic faceted navigation and targeted growth analysis.

Next steps

Updated 5 days ago

Did this page help you?