Filter for item listing quality metrics

Refer to the API throttling guide here to understand the usage limitations for this API.

To view a detailed description for all listing quality metrics, refer to the Content and Discoverability section in this Marketplace Learn article.

To view your seller’s listing quality score in the Seller Center, go to the Listing Quality Dashboard under Analytics > Growth Opportunities.

There are two ways to filter for an item’s specific listing quality metric that you want:

Filter fields – You can use filters with operators to specify the category or product type or select a range of values to return.

Query fields – You can use the query parameter to specify one of three fields: SKU, Title, or Item ID.

Option 1: Use filter field with operators

You can use filters in the request body to return specific metrics that you want to see for your items.

You can request an item’s score returned as percent value for these metrics using filters: content discoverability, quality, offer, ratings, and reviews. You can also filter for items that: have issues, are a specific product type, are within a category, or that are WFS-eligible.

Filter Operators

You need to specify the attribute to filter the responses returned, and an operator (either “equals” or “between”).

Filter Example: ProductType and Post-purchase Issues

To filter item details by Product Type and return all items with post-purchase issues, you can use the filters: viewPostPurchaseItems and productType.

This request will return all the items with post purchase issues for a specific product type:

{
"filters": [
{
"field": "viewPostPurchaseItems",
"op": "equals",

      "values": [0]
},
{
"field": "productType",
"op": "equals",
"values": ["Music"]
}
]

Option 2: Use query parameter with fields: SKU, title, condition, and item id

You can limit your search for item-level listing quality details either by: Item Title, SKU, condition, or Item ID with query fields: sku, title, condition, or itemId.

To specify the query parameter, you need to include the field and value in the body of the request.

Example Request Body: filter for item ID

For example, to query by item ID, specify field name itemId and Value(s) in the request body:

  "query": {
"field": "itemId",
"value": "916854860"
}

Similarly, you can specify the sku, title, or condition fields, and provide the value. You can also search multiple items, skus, or conditions with Comma-separated Value(s).

Example Request body: filter for multiple item ID

For example, to query by multiple item ID, specify the field name itemId and Value(s) in the request body:

"query": {
"field": ïtemId",
"value": "916854860,916854862,916854862,916854863"
}

Limit number of item details to return

To limit the number of items that return listing quality details, you can specify limit query parameter to only return a specific number of items in the response. By default, if no limit is specified, the API returns 200 items per page.

Use offset to return next set of 200 items

Use the offset query parameter to indicate pagination between each 200 items returned (the default limit). offset skips the first n items.

Example: offset returned in initial response

"offset": "200"

Specify this value in a subsequent request to return the next 200 items:

/v3/insights/item/listingQuality/items?offset=200

To get items 201-400, make a subsequent API call and specify the offset value to start the list to be returned.

Recommendations

• To fetch all items in your catalog, use offset along with a query parameter with a limit of 200.
• Item can be categorized by category or product type. To access this, mention category name or product type along with a limit of 200 to get as many items.
• Avoid accessing API’s one at time with itemId, SKU, or title fields to get multiple items. Rather use category, product type with a limit of 200 to get multiple items specific to the category, product type.