selling-partner-listing-issues

Overview

Fixes Selling Partner API (SP-API) listing problems that show up as reported issues on a listing: errors and warnings from missing or invalid attributes, and suppressions tied to an issue. It reads the listing's issues, explains each one in plain language, and proposes the exact attribute fix. Diagnosis is read-only; any fix is first drafted in validation-preview mode and shown to the seller, so nothing changes until they approve. It is the issue-fixing member of the SP-API listing troubleshooter family: "not buyable" with no issue and "cannot be found in search" are separate skills (see the sibling skills in Resources).

Workflow

<Definition - Listing Status> The summaries[].status field returned by the listings search operation is an array of independent states, not a single value. BUYABLE means customers can buy the item right now; DISCOVERABLE means it appears in search. A listing can be BUYABLE but not DISCOVERABLE (search-suppressed), or neither (fully suppressed). Both present with no ERROR issue means healthy. An empty issues[] does not mean healthy: a listing can be non-buyable or non-discoverable with no reported issue, and those causes belong to the sibling skills, not this one. Full detail is in references/issue-taxonomy.md. </Definition - Listing Status>

<Definition - Issue Object> Each entry in a listing's issues[] carries: code (Amazon's error code), message (human-readable description), severity (ERROR or WARNING), attributeName or attributeNames (the attribute at fault, which is what you fix), categories (for example MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, INVALID_PRICE), and enforcements.actions[].action (what Amazon did: LISTING_SUPPRESSED, SEARCH_SUPPRESSED, ATTRIBUTE_SUPPRESSED, or CATALOG_ITEM_REMOVED). An ERROR blocks the listing and is fixed first; a WARNING does not block it. Full detail, including the priority order, is in references/issue-taxonomy.md. </Definition - Issue Object>

<Definition - Validation Preview> A dry-run write: calling the listings patch operation with mode VALIDATION_PREVIEW returns the issues a change would produce and persists nothing. It is how every fix is checked and shown to the seller before a live write. Removing the mode and re-running the same call is the live submission. </Definition - Validation Preview>

<Workflow - Fix Listing Issues description="Diagnose a listing's reported issues read-only, then fix the blocking ones through previewed, approved attribute patches." tools=[] triggers=["fix my listing", "listing issues", "listing errors", "attribute errors", "suppressed because of an issue", "what's wrong with this listing"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. This skill reads and writes listings through that connector's listings search and patch operations. The connector is offered during onboarding, but the seller may have skipped it and added this skill manually. Validate: The connector is connected and its listings operations are reachable. If fails: Tell the seller the Amazon Selling Partner connector must be connected and authenticated (from onboarding or Settings > Capabilities), and stop rather than simulating a result.

2. [Agent] Establish account context (pre-resolved). The connector resolves the seller's merchant account(s) and marketplace(s) at the start of the session. Pin exactly one merchant account (entityId) and one marketplace before any call: if several accounts are in scope, ask which; if several marketplaces are in scope, ask which; if exactly one of each, use it. Keep this context in the session only. Validate: One entityId and one marketplaceId are pinned for the calls. If fails: Ask the seller for the missing identifier once, and do not guess a value.

3. [Agent] Scan the listing(s). Call the listings search operation with includedData=summaries,issues (add attributes or offers only when a specific fix needs them). Scope the scan: if the seller names a product or SKU, filter by that identifier; scan the whole catalog only when they ask to audit everything. Record each SKU's status, item name, and issues. Validate: A result is returned and each SKU's status array and issues[] are captured. If fails: If the read returns nothing or errors, report what came back and ask the seller to confirm the SKU or marketplace before retrying.

4. [Agent] Read status as context. The status array (BUYABLE, DISCOVERABLE) tells you how urgent an issue is, but this skill acts on issues that are present. If issues[] is empty but the listing is still not buyable or not discoverable, that cause belongs to a sibling skill. Validate: Each SKU is classified as having issues to fix here, or being a no-issue case to route. If fails: If a listing has no issues but is unhealthy, route it: not buyable to selling-partner-listing-buyability, not discoverable to selling-partner-listing-searchability, and say why.

5. [Agent] Triage the issues by impact. For each issue read severity, enforcements, attributeNames, and categories, and order them: ERROR + LISTING_SUPPRESSED first (not buyable, lost sales), then ERROR + SEARCH_SUPPRESSED, then ERROR + ATTRIBUTE_SUPPRESSED, then WARNING (does not block; do not alarm). See references/issue-taxonomy.md for what each value means. Validate: Issues are ordered worst-first and presented as a short table (SKU, status, severity, enforcement, attribute, what is wrong). If fails: If a field is missing or unfamiliar, consult references/issue-taxonomy.md rather than guessing its meaning.

6. [Decide] Are there several SKUs with issues?

   • Yes: render a small self-contained listing-health board (one row per SKU, colored by worst severity: red for ERROR or suppressed, amber for WARNING, green for healthy), with no external network calls, then continue.
   • No or a single SKU: continue without the visual.

7. [Agent] Explain each blocking fix. Name the exact attribute(s) to set and why, using a partial update so other attributes are never dropped. Fix a whole conditional group together when one attribute makes others required. For a complex attribute such as purchasable_offer, target the precise sub-path per references/fix-playbook.md rather than a top-level replace. If a fix needs an asset only the seller can supply (for example a hosted main image URL), ask them for it or hand off to Seller Central image upload; never invent it. Validate: Each blocking issue has a named attribute fix and a plain-language reason. If fails: If you cannot determine the attribute to fix, say so and consult references/fix-playbook.md; do not fabricate an attribute or value.

8. [Decide] Is the fix compliance-sensitive (claims, ingredients, category, condition, images, or identifiers)?

   • Yes: run the selling-partner-listing-compliance gate now. Continue to the preview only on the seller's explicit go from that gate; on a hold, summarize what is unmet and stop here.
   • No (a price, quantity, or typo fix): continue. Validate: The gate ran, or the fix was classified as not compliance-sensitive. If fails: If unsure whether a fix is compliance-sensitive, run the gate; it is cheap compared to a suppressed listing.

9. [Agent] Draft the fix in preview, do not execute. Call the listings patch operation with mode VALIDATION_PREVIEW for the corrected attribute(s) so nothing changes yet. Show the seller a numbered list: exact SKU and attribute, current then proposed value, the expected effect, and any issue the preview still reports. Validate: A preview result is produced and shown, with no live write yet. If fails: If the preview surfaces a new issue (for example a pricing or conditional-requirement error), show it and refine the patch; never carry an invalid fix forward to a live write.

10. [Ask user] Wait for explicit approval. Present the previewed change and ask the seller to approve or adjust. Do not write until they explicitly approve that specific change. Validate: The seller explicitly approves the specific previewed change. If fails: If they do not approve, adjust per their feedback and re-preview; make no live change.

11. [Agent] Apply only on approval. Re-run the same patch call without VALIDATION_PREVIEW. A live ACCEPTED means validation passed, not that the listing is fixed, since processing is asynchronous. Tell the seller it should clear shortly and offer to re-scan once (after a short wait or when they ask) to confirm BUYABLE or DISCOVERABLE returned; do not poll in a loop. Validate: The live patch returns and the seller is told acceptance is asynchronous, with a re-scan offered. If fails: If the write is rejected, report the exact error, return to the preview step, and refine before retrying.

12. [Agent] Summarize and flag cascading changes. Recap what was suppressed, what was drafted or fixed, and the single most important next action, in plain language. Remind the seller to check product packaging and advertisements for cascading changes they may want to make, and that changes must comply with Amazon's selling policies (per Rule 9). Validate: A short seller-friendly summary is produced with one clear next action. If fails: If the outcome of any fix is unknown, say so and offer the re-scan rather than asserting it is resolved.

</Workflow - Fix Listing Issues>

This skill depends on the built-in Amazon Selling Partner connector in Amazon Quick (see README.md ## Pre-requisites). The connector is offered during onboarding; if the seller skipped it, they connect and authenticate it from Settings > Capabilities.

Amazon Selling Partner API and Seller Central references (public):

• Amazon selling policies: https://sellercentral.amazon.com/help/hub/reference/GSNV3657R94YP9DZ
• Seller Central error-code explanations: https://sellercentral.amazon.com/help/hub/reference/external/G17781