The Catalog Search API 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

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 guide to understand the usage limitations for this API.

Request sample

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/items/catalog/search?page=0&limit=100' \ --header 'WM_CONSUMER.CHANNEL.TYPE: <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" }
}
'

import requests url = "https://marketplace.walmartapis.com/v3/items/catalog/search"
params = {"page": 0, "limit": 100} headers = { "WM_CONSUMER.CHANNEL.TYPE": "<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=<token> 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

{ "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 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 to confirm supported query/filter/sort fields by market, pagination behavior, and the latest status/error behavior before promoting changes to production.