This guide explains how to filter item-level listing quality data with the Item Listing Quality Details API. Use this guide to identify which items need attention and to focus on the specific metrics that affect listing quality, such as content, discoverability, offer quality, ratings, and reviews. It's especially useful when you need to:

• Find items with specific listing quality issues
• Narrow results by product type or other filterable attributes
• Search for a small set of items by SKU, title, condition, or item ID
• Limit the number of records returned in each response

How it works

At a high level, filtering listing quality metrics follows this workflow:

1. Call the Item Listing Quality Details API to retrieve item-level listing quality data.
2. Choose one of these filtering approaches:
   • Filters to narrow results by metric, issue state, category, product type, or score range
   • Query fields to search for specific items by sku, title, condition, or itemId
3. Review the returned items and identify which listings need updates.
4. Use the results to prioritize content fixes, discoverability improvements, pricing or offer updates, or review-related follow-up.

Prerequisites

Complete the following before you use the Item Listing Quality Details API:

• Seller or approved Solution Provider access to Walmart Marketplace APIs.
• Retrieve API keys (clientId and clientSecret) from the Developer Portal and use the keys to call Marketplace APIs.
• OAuth 2.0 authentication is required to access the Walmart Marketplace APIs. Ensure that you have obtained the necessary credentials and tokens before making API requests. For more information, refer to OAuth 2.0 authorization.
• Review API throttling guidance for usage limits on this API.

Endpoint

POST /v3/insights/items/listingQuality/items

Common scenarios

There are two ways to narrow the response:

• Use filters when you want to return a set of items that match a score range, product type, category, or issue condition.
• Use a query when you want to inspect an item by either SKU, title, or item ID.

Option 1: Use filters with operators

Use the filters array in the request body to return the subset of item metrics you want.

You can use filters to:

• Return items with specific issues
• Filter by product type or category
• Filter by metric ranges
• Return items based on score-related criteria

Supported operators in the current guide include:

Sample request

Use this request body to return items with post-purchase issues for a specific product type:

cURL --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic <BASE64_CLIENT_ID_CLIENT_SECRET>' \ --header 'WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>' \ --header 'WM_QOS.CORRELATION_ID: <UNIQUE_CORRELATION_ID>' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "filters": [ { "field": "viewPostPurchaseItems", "op": "equals", "values": [0] }, { "field": "productType", "op": "equals", "values": ["Music"] } ] }'

import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic <BASE64_CLIENT_ID_CLIENT_SECRET>", "WM_SEC.ACCESS_TOKEN": "<ACCESS_TOKEN>", "WM_QOS.CORRELATION_ID": "<UNIQUE_CORRELATION_ID>", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json",
} params = { "limit": 200
} payload = { "filters": [ { "field": "viewPostPurchaseItems", "op": "equals", "values": [0] }, { "field": "productType", "op": "equals", "values": ["Music"] } ]
} response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code)
print(response.text)

Modify your code

Replace placeholder values with values from your catalog:

• Replace Music with the product type you want to review.
• Update the field values only with fields supported by the API schema.
• Use equals for exact matches.
• Use between only when the field supports a numeric range.

For the complete list of supported filters and field descriptions, see the request body schema in the Item Listing Quality Details API Reference.

Option 2: Use a query field

Use the query object when you want to inspect specific items by known identifiers.

The current guide supports these query fields:

• sku
• title
• condition
• itemId

Sample request: query by item ID

cURL --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic <BASE64_CLIENT_ID_CLIENT_SECRET>' \ --header 'WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>' \ --header 'WM_QOS.CORRELATION_ID: <UNIQUE_CORRELATION_ID>' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "query": { "field": "itemId", "value": "916854860" } }'

import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic <BASE64_CLIENT_ID_CLIENT_SECRET>", "WM_SEC.ACCESS_TOKEN": "<ACCESS_TOKEN>", "WM_QOS.CORRELATION_ID": "<UNIQUE_CORRELATION_ID>", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json",
} params = { "limit": 200
} payload = { "query": { "field": "itemId", "value": "916854860" }
} response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code)
print(response.text)

Sample request: query by multiple item IDs

curl --request POST \ 'https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items?limit=200' \ --header 'Authorization: Basic <BASE64_CLIENT_ID_CLIENT_SECRET>' \ --header 'WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>' \ --header 'WM_QOS.CORRELATION_ID: <UNIQUE_CORRELATION_ID>' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "query": { "field": "itemId", "value": "916854860,916854862,916854863" } }'

import requests url = "https://marketplace.walmartapis.com/v3/insights/items/listingQuality/items" headers = { "Authorization": "Basic <BASE64_CLIENT_ID_CLIENT_SECRET>", "WM_SEC.ACCESS_TOKEN": "<ACCESS_TOKEN>", "WM_QOS.CORRELATION_ID": "<UNIQUE_CORRELATION_ID>", "WM_SVC.NAME": "Walmart Marketplace", "Accept": "application/json", "Content-Type": "application/json",
} params = { "limit": 200
} payload = { "query": { "field": "itemId", "value": "916854860,916854862,916854863" }
} response = requests.post(url, headers=headers, params=params, json=payload, timeout=30) print(response.status_code)
print(response.text)

Modify your code

Update the request body with real catalog values:

• Set field to sku, title, condition, or itemId.
• Replace value with your item identifier or search text.
• Use comma-separated values only for supported multi-value fields such as itemId or sku.

Limit the number of items returned

Use the limit query parameter to control how many item records the API returns.

The current guide states that if you do not specify a limit, the API returns 200 items per page by default, and the value cannot be negative.

Rate limits

If you submit too many feeds in a short period of time, you may exceed Walmart’s rate limits and receive HTTP 429 (Too Many Requests) responses. For more details on throttling and best practices, refer to the Rate Limiting Guide.

Next steps

After you filter item listing quality metrics, you can continue with these related tasks:

• Review the Insights API overview to understand how Listing Quality fits into the broader Insights API set.
• Retrieve your overall catalog score with the Seller Listing Quality ScoreAPI.
• Find categories with issues by using the Get Item Count with Listing Quality IssuesAPI.
• Review the full endpoint schema and response samples in the Item Listing Quality Details API reference.