selling-partner-listing-buyability

Overview

Answers "why can't customers buy this?" A Selling Partner API (SP-API) listing is buyable only when all three hold: the product is complete, there is a valid purchasable offer, and there is available inventory. This skill finds which one is missing, relays the state and the next step, and fixes the offer with the seller's approval. It does not invent data, and it only edits what the seller controls. It is the buyability member of the SP-API listing troubleshooter family; reported issues and search discoverability are separate skills (see the sibling skills in Resources).

Workflow

<Definition - Buyability Conditions> A listing is buyable only when all three hold at once: (1) the product is complete (no required attribute missing or invalid), (2) there is a valid purchasable offer (a price and condition the seller controls), and (3) there is available inventory. If any one is missing the listing is not buyable. This skill directly fixes only the offer; product completeness routes to selling-partner-listing-issues when it surfaces as a reported issue, and inventory routes to the inventory skills. </Definition - Buyability Conditions>

<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 buyable: a listing can lack an offer or be out of stock with no reported issue at all, so read the status array, not just the issue count. </Definition - Listing Status>

<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 an offer 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 - Diagnose Buyability description="Diagnose why a listing is not buyable across the three buyability conditions, then fix the offer with approval or route the cause to the right sibling skill." tools=[] triggers=["why can't customers buy this", "not buyable", "listing inactive", "no buy box", "missing price or offer", "why is this not for sale"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. This skill reads listings and patches the offer 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] Inspect the listing. Call the listings search operation with includedData=summaries,offers,attributes,issues for the SKU in question. Read summaries[].status (is BUYABLE present?), offers, and issues. Validate: A result is returned and the status array, offers, 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. [Decide] Find the cause, checking in this order:

   • Already BUYABLE: say so and stop.
   • No valid offer (offers empty or no price): the fix is to add a purchasable offer (price and condition). This is in scope; go to step 5.
   • Incomplete product (a required attribute missing or invalid, often an ERROR issue): relay what is missing. If it surfaces as a reported issue, hand to selling-partner-listing-issues.
   • Product complete and offer present but still not BUYABLE: almost certainly out of stock. Relay that as the likely cause and route: FBA to selling-partner-stockout-prevention or selling-partner-fba-inbound-management; merchant-fulfilled, point the seller to update the available quantity. Validate: Exactly one cause is identified, or a clean hand-off target is chosen. If fails: If the cause is ambiguous, relay what the data shows and ask the seller which direction to pursue rather than guessing.

5. [Agent] Frame whose data it is (for a product-data cause). Identify whether the missing or incorrect data is the seller's own contribution: if it is theirs, they can fix it and you can help draft the patch; if it is a shared catalog item they do not own, they can attempt a contribution but the change may need the listing owner or a support case. Say which; do not promise a fix you cannot make. Validate: The ownership path is stated for any product-data cause. If fails: If ownership is unclear, present both paths and let the seller decide.

6. [Decide] Does the offer fix change condition, or does the product-data path touch claims, ingredients, category, images, or identifiers?

   • Yes: run the selling-partner-listing-compliance gate now and continue only on the seller's explicit go.
   • No (price only): continue. Validate: The gate ran, or the fix was classified as price-only. If fails: If unsure, run the gate.

7. [Agent] Fix the offer in preview (for an offer cause). Draft the listings patch for purchasable_offer in mode VALIDATION_PREVIEW, targeting the precise sub-path rather than a top-level replace. Show current then proposed, 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, show it and refine the patch; never carry an invalid fix forward to a live write.

8. [Ask user] Wait for explicit approval. Present the previewed offer 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.

9. [Agent] Apply only on approval, then verify. Re-run the same patch call without VALIDATION_PREVIEW. A live ACCEPTED means validation passed, not that the listing is buyable yet, since processing is asynchronous. Offer to re-check once after a short wait that BUYABLE returned; do not poll in a loop. Validate: The live patch returns and the seller is told acceptance is asynchronous, with a re-check offered. If fails: If the write is rejected, report the exact error, return to the preview step, and refine before retrying.

10. [Agent] Summarize. State the single reason the listing was not buyable and the one next action taken or handed off (a drafted offer fix, an inventory hand-off, or a product-data path), in plain language. Validate: A short seller-friendly summary with one clear next action is produced. If fails: If the outcome is unknown (for example an async offer fix still processing), say so and offer the re-check rather than asserting it is buyable.

</Workflow - Diagnose Buyability>

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
• Supported operations for purchasable_offer: https://developer-docs.amazon.com/sp-api/docs/manage-purchasable-offer