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 which page of results to retrieve, starting from 0 (the first page).
• nextCursor: Used for cursor-based pagination. The API response will include a nextCursor value, which you can use to fetch the next set of results. This is especially useful for large data sets or when you prefer cursor-based navigation over page numbers. The nextCursor value expires in two minutes. If you need to continue paginating, you must repeat the steps to obtain a new nextCursor value for each subsequent request.

Initial request: Offset-based pagination

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

   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" } } '
   

2. 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)

   JSON

   { "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
   }
   

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

Initial request: Cursor-based pagination

1. 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" } } '

2. 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 ] }

3. 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. Note that the nextCursor value expires in two minutes. If it expires, you must repeat the steps to get a new nextCursor value for subsequent requests.
4. 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" } }