Guides
My Account

Get categorization API

Overview

The Get categorization API provides a primary sort of the brands by recommendation count, then a secondary sort in alphabetical order.

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

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 about 5 hours ago