---
updatedAt: 2026-07-30T22:19:44.000Z
---
# Catalog search for the seller catalog
The **[Catalog Search API](/us-marketplace/reference/getcatalogsearch)** lets you search your seller catalog by submitting a request payload with query, filters, and sort options. It supports searching by attributes such as SKU, product name (wildcard supported), price, publication status, and rating, and it supports pagination using page/limit as well as cursor-based pagination with `nextCursor`.
### Use cases
* Search your seller catalog by identifiers (for example, SKU, WPID, UPC, GTIN).
* Find items by lifecycle and publication status (for example, ACTIVE vs RETIRED; PUBLISHED vs UNPUBLISHED).
* Filter items based on rating/reviews or other supported attributes.
* Retrieve and review variant group details when returned in results.
### Benefits
* Flexible search: combine **query + filters + sort** in one request.
* Pagination support for large result sets (`page`/`limit` and `nextCursor`).
* Wildcard search support for `productName`.
## Reference guide
This guide explains how to use the catalog search API to search your Seller Catalog using a structured request body (query, filters, sort) and paginate through results.
For full technical details, including endpoints, parameters, and brief descriptions, refer to the catalog search API reference.
***
# Endpoint
```http
POST https://marketplace.walmartapis.com/v3/items/catalog/search
```
## Query parameters
* `page` (int32, default **0**): Indicates which page of results to retrieve.
* `limit` (int32, default **100**): Specifies the number of items to retrieve per page.
* `nextCursor` (string): Used for cursor-based pagination to retrieve the next set of items.
**Throttling:** Refer to the [API throttling](/us-marketplace/docs/rate-limiting) guide to understand the usage limitations for this API.
***
# Request sample
```curl
curl --request POST \
--url 'https://marketplace.walmartapis.com/v3/items/catalog/search?page=0&limit=100' \
--header 'WM_CONSUMER.CHANNEL.TYPE: ' \
--header 'WM_GLOBAL_VERSION: 3.1' \
--header 'WM_MARKET: us' \
--header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \
--header 'WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....' \
--header 'WM_SVC.NAME: Walmart Service Name' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"query": {
"field": "sku",
"value": "12345678"
},
"filters": [
{
"field": "customerRating",
"op": "greater_than",
"values": [
"5"
]
}
],
"sort": {
"field": "num_reviews",
"order": "ASC"
}
}
'
```
```python
import requests
url = "https://marketplace.walmartapis.com/v3/items/catalog/search"
params = {"page": 0, "limit": 100}
headers = {
"WM_CONSUMER.CHANNEL.TYPE": "",
"WM_GLOBAL_VERSION": "3.1",
"WM_MARKET": "us",
"WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6",
"WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....",
"WM_SVC.NAME": "Walmart Service Name",
"accept": "application/json",
"content-type": "application/json",
}
payload = {
"query": {"field": "sku", "value": "12345678"},
"filters": [{"field": "customerRating", "op": "greater_than", "values": ["5"]}],
"sort": {"field": "num_reviews", "order": "ASC"},
}
resp = requests.post(url, headers=headers, params=params, json=payload, timeout=30)
print("Status:", resp.status_code)
print(resp.text)
```
## Modify your code
You can customize results by adjusting pagination, query, filters, and sort in the request. Start with a targeted query, then refine results with filters and sorting, and paginate through larger result sets as needed.
1. **Choose your query**
* Pick a `query.field` that matches how you identify items (for example, `sku`, `productName` (wildcard supported), `gtin` (14 digits), `wpid`, `upc` (12 digits), or `itemId`).
* Set `query.value` to the identifier or search term you want to find.
2. **Call the catalog search endpoint**
* Send a `POST` request to `/v3/items/catalog/search` with your request body containing `query` (and optionally `filters` and `sort`).
* Send required headers and any optional headers as needed.
3. **Refine results with filters (optional)**
* Add one or more filter objects in `filters` to narrow results (for example, rating, lifecycle status, publication status).
* Use supported operators only: `equals`, `between`, `greater_than`, `less_than`.
4. **Control ordering with sorting (optional)**
* Set `sort.field` and `sort.order` to control result order.
* Allowed `sort.order` values: `ASC`, `DESC`.
5. **Paginate results**
* Use `page` and `limit` in the URL to page through results (example: `?page=1&limit=50`).
* If the response includes `nextCursor`, pass it as `?nextCursor=` to fetch the next set of results.
6. **Review the response**
* Review the returned results to identify the items you want to investigate or take action on (for example, publishing decisions, lifecycle checks, catalog maintenance).
* Keep paginating (page/limit or `nextCursor`) until you’ve retrieved the items you need.
***
# Response samples
## Sample 1: 200 Search items
```json
{
"All": 682
}
```
## Sample 2: 200 with variant information
```json
{
"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 call (**200**):
* You receive a response that may include a `payload` list of matched items and pagination metadata (for example, `limit`, `totalItems`, and `nextCursor`).
* Each item includes a set of item attributes (for example, identifiers, lifecycle/publication status, pricing, descriptive details, and other catalog metadata).
***
## Next steps
* Start with a precise `query.field` (for example, SKU or GTIN) and add filters only as needed.
* Use `page`/`limit` for simple pagination, and `nextCursor` for efficient deep pagination across large result sets.
* Add request logging with `WM_QOS.CORRELATION_ID` for traceability and support.
* Refer to the [API reference documentation](/us-marketplace/reference/getcatalogsearch) to confirm supported query/filter/sort fields by market, pagination behavior, and the latest status/error behavior before promoting changes to production.