Filter, search, and sort items
The filters in the Get RAP post-purchase items API allows you to retrieve a customized list of items that are eligible for the RAP. You can apply various filters to narrow down your results, such as selecting items from a specific category or within a certain price range.
While the itemStatus
filter is mandatory, other filters like dateRange
, category
, and price
are optional, giving you flexibility in your queries. The dateRange
filter also enables you to analyze item impressions, page views, and sales over 7, 14, or 30 days. By using this API, you can search, filter, and sort items according to your business needs, making it easier to identify and analyze products that meet your RAP criteria and review their performance metrics.
Note: This page describes an example using only the required parameters and inputs to filter, search, and sort items in the RAP. For a full list of customization options and additional capabilities, refer to the
Walmart Reviews API reference guide.
How it works
- Filters:
- Only items with
itemStatus
:ELIGIBLE
(eligible for the program) - Items within the specified
dateRange
(For example,dateRange
:7DAYS
) - Items in the specified categories (For example,
32 JEWELRY
orSHOES
) - Items between the minimum and maximum price range (For example, $10 and $100)
- Only items with
- Search:
- Only items with a specified value in a field (For example, items whose name contains the word "kids" in the
ITEM_NAME
)
- Only items with a specified value in a field (For example, items whose name contains the word "kids" in the
- Sort:
- First, sort by
ITEM_PRIORITY
in ascending order (lowest priority first) - If items have the same priority, sort those by
PRICE
in descending order (highest price first)
- First, sort by
- The response returns detailed information for each matching item, such as item ID, name, sales, reviews, impressions, page views, reviews collected, SKU, item status, and priority. The response includes metadata like total items, fetched items, date range, and scrollId for pagination.
Endpoint
GET https://marketplace.walmartapis.com/v3/growth/reviews-accelerator/items
Sample request
This example shows you how to set the necessary headers and structure your API call to retrieve a list of items eligible for the RAP. It demonstrates how to include required headers such as content-type
and accept
, and how to format the JSON payload to specify a filter (in this case, filtering by itemStatus: ELIGIBLE
). The scrollId=*
parameter is used for pagination, allowing you to scroll through large sets of results. Use this sample as a starting point, then modify it with your actual data and any additional parameters as described in the API reference.
curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/growth/reviews-accelerator/items?scrollId=*' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '
{ "filter": { "itemStatus": "ELIGIBLE", "dateRange": "7DAYS", "category": [ "32 JEWELRY", "SHOES" ], "price": { "minimum": 10, "maximum": 100 } }, "search": [ { "value": "kids", "field": "ITEM_NAME" } ], "sort": [ { "field": "ITEM_PRIORITY", "order": "ASC", "priority": 1 }, { "field": "PRICE", "order": "DESC", "priority": 2 } ]
}
'
import requests url = 'https://marketplace.walmartapis.com/v3/growth/reviews-accelerator/items?scrollId=*' headers = { 'accept': 'application/json', 'content-type': 'application/json', # 'Authorization': 'Bearer <YOUR_ACCESS_TOKEN>' # Uncomment and set your token if required
} payload = { "filter": { "itemStatus": "ELIGIBLE", "dateRange": "7DAYS", "category": ["32 JEWELRY", "SHOES"], "price": { "minimum": 10, "maximum": 100 } }, "search": [ { "value": "kids", "field": "ITEM_NAME" } ], "sort": [ { "field": "ITEM_PRIORITY", "order": "ASC", "priority": 1 }, { "field": "PRICE", "order": "DESC", "priority": 2 } ]
} response = requests.post(url, headers=headers, json=payload) print("Status Code:", response.status_code)
try: print("Response JSON:", response.json())
except Exception: print("Response Content:", response.text)
Modify your code
- Replace the example values in the
category
array with the actual categories you want to filter by. - Adjust the price range by changing the
minimum
andmaximum
values to match your desired price limits. - Update the
search
field to use a different keyword or search field as needed (For example, changekids
to another term, or search by a different field). - Modify the sort array to change the sorting order, fields, or priorities according to your requirements (For example, sort by a different field or change the order from
ASC
toDESC
). - Add or remove filter fields as needed, based on your specific use case.
Sample response
The following is a sample successful response provided by the API.
{ "statusCode": 200, "payload": { "totalItems": 1, "fetchedItems": 1, "dateRange": "7DAYS", "scrollId": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAACUyUsWamJiNUxwcDJUU0dxbHBObmJvRUF2UQ==", "items": [ { "itemId": "100015964", "itemName": "View-Master Discovery Kids 3D Marine Life Toy Viewfinder Reel", "sales": 122, "currentReviews": 3, "impressions": 81421, "currentPageViews": 2342, "reviewsCollected": 0, "sku": "NK-WHT2XL", "itemStatus": "ELIGIBLE", "itemPriority": 1 } ] }
}
Result
If successful, the API responds with an HTTP status: 200 OK
and a JSON payload containing a list of items that match your filter criteria. In this example, the filter is set to retrieve items with an itemStatus
of ELIGIBLE
within the last 7 days.
For each item, the response includes details such as itemId
, itemName
, and sku
, along with additional information like sales, current reviews, impressions, page views, reviews collected, item status, and item priority.
If there are more items to retrieve, the response will also include a scrollId
for pagination. If any items failed to process, the response may include error details such as itemId
, errorCode
, errorDescription
, severity
, and category
.
Use this information to verify which items were successfully filtered and to handle any errors or pagination as needed.
Updated 1 day ago