Catalog search for the seller catalog
Overview
Use the Catalog Search API to search your Walmart Marketplace seller catalog using a structured request containing query, filter, and sort options.
You can search by product identifiers, product name, publication status, pricing, and other supported attributes. The API also supports wildcard searches and pagination to help retrieve items from larger catalogs.
Use cases
- Search your seller catalog by identifiers such as SKU, WPID, UPC, or GTIN.
- Find items by lifecycle or publication status.
- Filter items by customer rating, number of reviews, or other supported attributes.
- Combine query, filters, and sorting to refine search results.
- Retrieve variant group information when available.
- Navigate large result sets using page-based or cursor-based pagination.
Reference guide
This guide explains how to search your seller catalog using query, filters, and sort options, and how to retrieve paginated results.
For complete endpoint details, parameters, and response definitions, refer to the Catalog Search API Reference.
Endpoint
POST https://marketplace.walmartapis.com/v3/items/catalog/searchRequest sample
The following request searches for an item using its SKU.
curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/items/catalog/search?page=0&limit=100' \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_MARKET: us" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>" \ -H "WM_GLOBAL_VERSION: 3.1" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "query": { "field": "sku", "value": "12345678" } }'Replace <ACCESS_TOKEN> with a valid access token and use a unique correlation ID for each request.
For Global requests, set WM_MARKET to the applicable marketplace.
Modify your request
Customize your search using query, filters, and sort in the request body. Use page, limit, or nextCursor to navigate through results.
Search for items
Set query.field to the attribute you want to search and query.value to the search term or identifier.
Supported search attributes include sku, productName, gtin, wpid, upc, and itemId.
The API supports wildcard searches using % to represent unknown characters. For example, %n% searches for SKUs containing the letter n.
{ "query": { "field": "sku", "value": "%n%" }
}Filter and sort results
Use filters to narrow results based on supported attributes such as price, publication status, customer rating, or number of reviews.
Supported filter operators: equals, between, greater_than, less_than.
Use sort.field and sort.order to control result ordering. Allowed sort.order values: ASC, DESC.
You can combine query, filters, and sort in a single request:
{ "query": { "field": "sku", "value": "%n%" }, "filters": [ { "field": "price", "op": "greater_than", "values": [10] } ], "sort": { "field": "num_reviews", "order": "ASC" }
}Include a query or filter when applying sorting.
Control page-based pagination
Use page and limit to retrieve results in batches.
page: Page number, starting at0. Default:0.limit: Number of items returned per page. Default:100.
For the first page:
POST /v3/items/catalog/search?page=0&limit=100For the next page:
POST /v3/items/catalog/search?page=1&limit=100Control cursor-based pagination
Use nextCursor to retrieve additional results.
For the initial cursor-based request, set nextCursor to *.
POST /v3/items/catalog/search?limit=100&nextCursor=*If the response includes a nextCursor, pass the returned value in a subsequent request:
POST /v3/items/catalog/search?limit=100&nextCursor=<NEXT_CURSOR>The cursor expires after two minutes. If it expires, restart pagination with a new initial request.
Response samples
Sample 1: 200 Search items
{ "All": 682
}Sample 2: 200 with variant information
{ "status": "Success", "payload": [ { "gtin": "05420529997042", "wpid": "5DTSM799JCUI", "lifecycleStatus": "RETIRED", "mart": "WALMART_US", "publishedStatus": { "reasons": [ "END_DATE" ], "status": "UNPUBLISHED" }, "productName": "Electronic Cables", "manufacturer": "ECManu", "shelf": [ "UNNAV" ], "itemId": "562433848", "price": { "amount": 70, "unit": "USD" }, "variantGroupInfo": { "groupingAttributes": [ { "name": "actual_color", "value": "1234567890" } ], "isPrimary": "true" }, "variantGroupId": "Toysgroup0101", "sku": "88nZ6RR82XghDkd", "brand": "ECB brand", "productType": "default" } ], "limit": 10, "totalItems": 126331, "nextCursor": "DnF1ZXJ5VGhlbkZldGNoFAAAAAAFY5rZFmJYLXU3cXBtUkptLUh5Rl9SelItZmcAAAAAAyAIRRZ4Mm41WTB1UlFIUzkyUVlOSjhFWXV3AAAAAAMgCEYWeDJuNVkwdVJRSFM5MlFZTko4RVl1dwAAAAAFhKggFmswVURRXzhzUlYtQVhyRmVXTy1UN0EAAAAABYSoHxZrMFVEUV84c1JWLUFYckZlV08tVDdBAAAAAAWt5AIWTl82dF9OR09Uc2VXbVhwRUFUSk44ZwAAAAAFTM_uFk11Q04ydmlOUk1pNW1iS0paUUt6Q1EAAAAABUzP7xZNdUNOMnZpTlJNaTVtYktKWlFLekNRAAAAAAWEqCIWazBVRFFfOHNSVi1BWHJGZVdPLVQ3QQAAAAAFhKghFmswVURRXzhzUlYtQVhyRmVXTy1UN0EAAAAABWOa2hZiWC11N3FwbVJKbS1IeUZfUnpSLWZnAAAAAAVMz_EWTXVDTjJ2aU5STWk1bWJLSlpRS3pDUQAAAAADIAhHFngybjVZMHVSUUhTOTJRWU5KOEVZdXcAAAAABWOa3BZiWC11N3FwbVJKbS1IeUZfUnpSLWZnAAAAAAWt5AMWTl82dF9OR09Uc2VXbVhwRUFUSk44ZwAAAAAFY5rbFmJYLXU3cXBtUkptLUh5Rl9SelItZmcAAAAABUzP8BZNdUNOMnZpTlJNaTVtYktKWlFLekNRAAAAAAMgCEgWeDJuNVkwdVJRSFM5MlFZTko4RVl1dwAAAAAFreQFFk5fNnRfTkdPVHNlV21YcEVBVEpOOGcAAAAABa3kBBZOXzZ0X05HT1RzZVdtWHBFQVRKTjhn"
}Results
After a successful request, the API returns matching catalog items and pagination information. Depending on the matching items, the response may include product identifiers, listing status, pricing, and variant group details.
Next steps
- Use Get an item to retrieve detailed information about a specific item.
- Use Get all items to retrieve items using supported query parameters.
- Use Get item count by status to review catalog publication counts.
- Refer to the API reference for the complete list of supported search and filter attributes.
Updated 12 days ago

