selling-partner-listing-troubleshooter

Overview

The front door for listing problems in a Selling Partner API (SP-API) session. A seller rarely knows whether their issue is a reported issue, a buyability problem, or a searchability problem. This skill does one quick read of the listing's status and issues, identifies the symptom, and routes the seller to the right specialist skill. It diagnoses and directs; it makes no changes itself, since each specialist owns its own fix behind its own approval gate. It is the router of the SP-API listing troubleshooter family (see the specialist 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, or neither. An empty issues[] does not mean the listing is healthy: it can be non-buyable or non-discoverable with no reported issue, which is exactly why this skill reads the status array, not just the issue count, before routing. </Definition - Listing Status>

<Definition - Routing Map> How this skill classifies a symptom and where it sends the seller:

• Reported issues present (errors or warnings to fix) route to selling-partner-listing-issues.
• Not BUYABLE with no offer, an incomplete product, or out of stock routes to selling-partner-listing-buyability.
• Not DISCOVERABLE, "cannot be found," or "improve ranking or visibility" routes to selling-partner-listing-searchability.
• "Can I list this," "what do I need to sell X," "is this compliant," or a new product with no listing yet routes to selling-partner-listing-compliance. When more than one applies, lead with the most impactful (not buyable, then not found, then a quality warning). </Definition - Routing Map>

<Workflow - Route Listing Problem description="Do one read to classify a non-specific listing complaint, then route the seller to the right specialist skill with a plain-language reason." tools=[] triggers=["something's wrong with my listing", "troubleshoot my listing", "my product has a problem", "listing not working", "where do I start"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. This skill does one read of the listing through that connector's listings search operation. 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 search operation is 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 call. If fails: Ask the seller for the missing identifier once, and do not guess a value.

3. [Decide] Did the seller already name the symptom?

   • Yes (for example "it's not buyable", "it's not showing up in search", "it has errors"): skip the classification read and route straight to that specialist (selling-partner-listing-buyability, selling-partner-listing-searchability, or selling-partner-listing-issues).
   • No (non-specific "something is wrong"): continue to step 4. Validate: A clear branch is chosen. If fails: If it is unclear whether the symptom is named, treat it as non-specific and continue to step 4.

4. [Agent] Quick scan. Call the listings search operation with includedData=summaries,issues for the SKU in question. Read summaries[].status (is BUYABLE present? is DISCOVERABLE present?) and issues[]. Validate: A result is returned and the 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.

5. [Agent] Classify the symptom against the Routing Map, and scan all signals, not just the first. A listing can match more than one path, so note every symptom present (reported issues, not buyable, not discoverable, inventory). Validate: Every applicable symptom is identified, not just the first one seen. If fails: If no symptom is clear (status looks healthy and issues[] is empty), do not declare the listing fine: tell the seller what you read and ask what they are experiencing, since a problem can exist with no reported issue.

6. [Decide] How many symptoms apply?

   • One: route to that specialist per the Routing Map.
   • More than one: lead with the most impactful (not buyable, then not found, then a quality warning), route there first, and offer to address the others afterward. Validate: A single most-impactful destination is chosen, with any others noted for follow-up. If fails: If impact ordering is unclear, present what you found and let the seller choose which to tackle first.

7. [Agent] Route with a reason. Tell the seller the symptom you read and which specialist skill you are handing off to and why (for example "you are not buyable and there is no offer, so let's use the buyability troubleshooter"), then continue in that skill. Validate: The seller is given the destination and the reason before the hand-off. If fails: If you cannot articulate why, re-read the signals rather than routing blindly.

</Workflow - Route Listing Problem>

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.