Limit and pagination

Use the Catalog Search API to search for items in the Walmart Marketplace catalog. This API allows you to:

Search for catalog items by specific attributes. For example, Product name, SKU, condition, and so on
Filter results based on specific fields. For example, Number of reviews, customer rating, published status, and so on
Sort the results as needed
Retrieve results in a paginated manner for efficient data handling

Endpoint

POST https://marketplace.walmartapis.com/v3/items/catalog/search

Query parameters

The Catalog Search API supports flexible pagination using the limit, page, and nextCursor query parameters. Here’s how each parameter works:

limit: Specifies the number of items to return per page. If not specified, the default is 100.
page: Indicates the page number to retrieve, starting from 0 for the first page.
nextCursor: Used for cursor-based pagination. The nextCursor value is provided in the API response and can be used to fetch the next set of results, especially when the data set is large or when using cursor-based navigation is preferred over page numbers.

Initial request: Offset-based pagination

Send your first request with parameters such as page=0 and limit=100 in the endpoint.
/v3/items/catalog/search?page=0&limit=100

Example request

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/items/catalog/search?page=0&limit=100' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "query": { "field": "productName", "value": "string" }, "filters": [ { "field": "num_reviews", "op": "equals", "values": [ "string" ] } ], "sort": { "field": "num_reviews", "order": "ASC" } } '

The API returns up to 100 items as set by thelimit parameter. The totalItems parameter shows the total number of matching items, and page indicates the current page number.

Example response (Limit of 100)

{ "items": [ { "itemId": "123456789", "productName": "Sample Product Name", "num_reviews": 100, "price": 19.99, "brand": "SampleBrand", "productType": "SampleType" } // ... up to 100 items ], "totalItems": 1000, "page": 0, "limit": 100
}

To get the next set of items, increase the page value to 1, 2, etc. in your next request.

Initial request: Cursor-based pagination

Send your first request with parameters such as limit=100 and nextCursor= in the endpoint.
/v3/items/catalog/search?limit=100&nextCursor=
Example request

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/items/catalog/search?limit=100&nextCursor=*' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "query": { "field": "productName", "value": "string" }, "filters": [ { "field": "num_reviews", "op": "equals", "values": [ "string" ] } ], "sort": { "field": "num_reviews", "order": "ASC" } } '

The API returns up to 100 items and, if there are more results, includes a nextCursor value in the response.
Example response (Limit of 100)

{ "status": 200, "limit": 100, "page": 0, "totalItems": 250, "nextCursor": "7aafd076-c0a8-4ed7-8f12-2f3fc52a1679", "payload": [ // up to 100 item objects here ] }

After the first request, reuse the same nextCursor value from the previous response in your next request.
/v3/items/catalog/search?limit=100&nextCursor=7aafd076-c0a8-4ed7-8f12-2f3fc52a1679.

The API returns the next batch of items.
Continue to reuse the same nextCursor value for each subsequent request until you reach the end of the results or the cursor expires.

Search using only the query parameter

Wildcard search is supported for query. In the following example, % is used to indicate unknown. So, in this case, it will search any SKU containing letter n.

{ "query": { "field": "sku", "value": "%n%" } }

Search using the filter parameter

Multiple fields are supported in filters. You can combine any filters you like to search. In this case, we are doing a search for all the items which match these two criteria – price is larger than 10 and unpublishedStatus is either PUBLISHED or RETIRED.

{ "filters": [ { "field": "price", "op": "larger_than", "values": [ 10 ] }, { "field": "unpublishedStatus", "op": "equals", "values": [ "PUBLISHED", "RETIRED" ] } ] }

Search using the sort parameter

Sorting is specified with the order parameter, and it allows you to sort your search results on specific fields. You must have either query or filters before Sort, and it supports either ascending (ASC) or descending (DESC).

{ "sort": { "field": "unpublishedStatus", "order": "ASC" } }

Search using only the query, filter, and sort parameters

{ "query": { "field": "sku", "value": "%n%" }, "filters": [ { "field": "price", "op": "larger_than", "values": [ 10 ] }, { "field": "unpublishedStatus", "op": "equals", "values": [ "PUBLISHED", "RETIRED" ] } ], "sort": { "field": "unpublishedStatus", "order": "ASC" } }