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/search

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

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 at 0. Default: 0.
  • limit: Number of items returned per page. Default: 100.

For the first page:

POST /v3/items/catalog/search?page=0&limit=100

For the next page:

POST /v3/items/catalog/search?page=1&limit=100

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

Did this page help you?