Limit and pagination

Limit is a query parameter which specifies the total items to return. You can simply attach the limit and pagination/nextCursor at the end of url. Do not apply nextCursor when you do the search for the first time. For the first request, the value of nextCursor will be an asterisk.

Defined limit and pagination

/v3/items/catalog/search?limit=limit&nextCursor=* 

Example request: Limit of 1

/v3/items/catalog/search?limit1=1&nextCursor=*

The response for above request with limit of 1 would be:

Example response: Limit of 1

{ "status": 200, "limit": 1, "totalItems": 2, "nextCursor": "7aafd076-c0a8-4ed7-8f12-2f3fc52a1679", "payload": \[ { "mart": "WALMART_US", "sku": "HCA-112", "condition": "New", "wpid": "23MYQ7CNGDPI", "upc": "788244013504", "gtin": "00788244013504", "productName": "Tenpoint Premium Cable String Lubricant with Foam Applicator", "shelf": "[\"Home Page\",\"Sports & Outdoors\",\"Sports & Outdoors Shop by Brand\",\"TenPoint Crossbows\"]", "productType": "Machine & Tool Lubricants", "price": { "currency": "USD", "amount": 18.95 }, "publishedStatus": { "status": "PUBLISHED" }, "lifecycleStatus": "ACTIVE" } ] }

The response includes the nextCursor value to be sent to retrieve the next page. In this case, the value is 7aafd076-c0a8-4ed7-8f12-2f3fc52a1679. For example, if the selected limit is 10 and nextCursor is applied, it will look as follows:

Example request: Limit of 10

/v3/items/catalog/search?limit=10&nextCursor=7aafd076-c0a8-4ed7-8f12-2f3fc52a1679 

Example: 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%" } }

Example: 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" ] } ] }

Examples: 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" } }

Examples: 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" } }