Search item issues

Overview

Use the search item issues API to retrieve item-level diagnostic issues that block or limit items in active Search Engine Marketing (SEM) campaigns. Each result identifies which items are blocked or limited from serving, the issues affecting them, and the campaigns they belong to. Use this data to prioritize fixes and unblock items from advertising on external channels such as Google.

The API returns paginated item-level diagnostics for items in active SEM campaigns, including:

• Campaign associations
• Issue categories
• Issue types
• Product details
• Remediation references

By default, only items with issues (BLOCKED or LIMITED) are returned. To include healthy items, explicitly filter with issueCategory=NO_ISSUES.

Use cases

Use this endpoint to:

• Search for blocked or limited items across active campaigns
• Filter diagnostics by issue type, category, or item ID
• Paginate through large catalog results
• Feed item-level diagnostics into remediation workflows

Endpoint

POST /v3/advertising/sem/item-issues/search

Default behavior

When no request body is provided:

• offset=0
• limit=100
• Returns only BLOCKED and LIMITED items

Supported filters

Request sample

curl --request POST \ --url 'https://marketplace.walmartapis.com/v3/advertising/sem/item-issues/search' \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_MARKET: US' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'WM_SEC.ACCESS_TOKEN: <Your_access_token>' \ --header 'WM_GLOBAL_VERSION: 3.1' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "page": { "offset": 0, "limit": 20 }, "filters": [ { "field": "issueCategory", "values": ["BLOCKED"] } ] }'

import requests url = "https://marketplace.walmartapis.com/v3/advertising/sem/item-issues/search" headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_MARKET": "US", "WM_SVC.NAME": "Walmart Marketplace", "WM_SEC.ACCESS_TOKEN": "<Your_access_token>", "WM_GLOBAL_VERSION": "3.1", "Accept": "application/json", "Content-Type": "application/json"
} payload = { "page": { "offset": 0, "limit": 20 }, "filters": [ { "field": "issueCategory", "values": ["BLOCKED"] } ]
} response = requests.post(url, headers=headers, json=payload)
print(response.json())

Modify your code

You can customize the request to retrieve specific diagnostics data:

• Update offset and limit to paginate through large result sets
• Use the issueCategory filter to retrieve only BLOCKED, LIMITED, or NO_ISSUES items
• Use the issues filter to retrieve items affected by specific issue types
• Use the itemId filter to retrieve diagnostics for specific Walmart item IDs
• Combine multiple filters to narrow search results

Example customization

{ "filters": [ { "field": "issues", "values": ["TITLE_TOO_LONG"] } ]
}

Response sample

{ "pagination": { "pageNo": 0, "pageSize": 20, "totalCount": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false }, "data": [ { "offerId": "ABC123DEF456", "itemId": "123456789", "sku": "PARTNER-SKU-001", "productName": "Samsung Galaxy Buds Pro", "issueCategory": "BLOCKED", "campaignAssociations": [ { "campaignId": "98765", "campaignName": "Electronics Summer Sale" } ], "issues": [ { "issueType": "ITEM_OUT_OF_STOCK" } ] } ]
}

Results

A successful response returns paginated item-level SEM diagnostics. Each item includes campaign associations, issue severity (BLOCKED, LIMITED, or NO_ISSUES), and issue type identifiers affecting the item’s SEM eligibility.

Error handling

Common issue categories

Best practices

• Cache issue metadata locally using the issue types endpoint
• Prioritize BLOCKED issues first
• Default dashboards to show only actionable issues
• Use pagination for large catalogs
• Surface fixable issues prominently in partner workflows
• Schedule recurring diagnostics scans

Next steps

After retrieving diagnostics:

• Use the GET /item-issues/issue-types endpoint to enrich issue metadata
• Build remediation workflows for sellers
• Integrate diagnostics into SEM campaign dashboards
• Automate recurring SEM health monitoring