Preview Listing Patches Before They Go Live

The Slack message came in right before a weekend push: "Our luggage listing is converting badly, the bullets read like a wall of text, and one image got rejected last week. Can the agent just fix it? But I don't want it quietly editing a live listing without me seeing what changed first."

That last clause is the whole job. Fixing a listing is easy to ask for and dangerous to automate, because a single wrong attribute name can wipe a field you never meant to touch. So I handed it to our agent, backed by Amazon Agent Atlas, with one rule: audit first, show me the diff, and do not write anything live until I say yes.

What a model without Atlas gets wrong

I gave the same prompt to a frontier model with no retrieval. The plan it produced looked reasonable and would have caused real damage.

None of this is exotic. It is all in Amazon's own documentation, scattered across the Selling Partner API (SP-API) reference and a handful of Seller Central help pages that only surface when you already know the exact term to search.

What Atlas retrieves

When the agent gets the question, it runs a semantic search across the amazon_sellers collection and pulls the governing documents before it writes a single attribute:

• The Partially Update a Listing reference, which establishes that patchListingsItem applies a JSON Patch to one or more attributes without disturbing the rest of the listing.
• The Preview Errors Before Partially Updating a Listing tutorial, the source of the mode=VALIDATION_PREVIEW parameter that turns a blind submission into a dry run.
• The Catalog Items API reference, whose getCatalogItem call returns the live attributes, images, and summaries for an ASIN (Amazon Standard Identification Number), keyed to the product type definition.
• Suppressed Listings Management, which explains how to download the suppressed listings report and why a listing is hidden from search in the first place.
• Product Image Requirements for Amazon Listings, which states plainly that non-compliant images suppress the listing from search until compliant images are provided.
• Suggest Changes to Your Product Detail Page, Amazon's own surface for recommended detail-page improvements, which the agent reads as a second opinion on what to fix.

Atlas does not write the patch. It surfaces the rules the patch has to obey, wired through the Amazon Selling Partner MCP, and the agent adapts them to this specific listing.

The agent's working output

The agent did not start by editing anything. It pulled the live listing state through getCatalogItem and produced an audit report that names each finding, its severity, and the document it is grounded in:

{
  "asin": "B0EXAMPLE12",
  "sku": "LUG-HARDSIDE-28",
  "listing_status": "active",
  "findings": [
    {
      "field": "bullet_point",
      "severity": "high",
      "finding": "Two bullets exceed 255 characters and one contains an emoji",
      "source": "Product Bullet Points Requirements"
    },
    {
      "field": "main_image",
      "severity": "medium",
      "finding": "Main image background is not pure white; at risk of suppression",
      "source": "Product Image Requirements for Amazon Listings"
    },
    {
      "field": "item_name",
      "severity": "low",
      "finding": "Title repeats the brand token three times",
      "source": "Suggest Changes to Your Product Detail Page"
    }
  ]
}

From that audit, the agent built a JSON Patch that touches only the bullet points, leaving every other attribute untouched. This is the body it would send to patchListingsItem:

{
  "productType": "LUGGAGE",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/bullet_point",
      "value": [
        {
          "value": "Hardside shell resists scuffs and cracking on checked flights",
          "marketplace_id": "ATVPDKIKX0DER"
        },
        {
          "value": "Spinner wheels roll in four directions for tight gate turns",
          "marketplace_id": "ATVPDKIKX0DER"
        },
        {
          "value": "TSA-approved combination lock built into the side panel",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    }
  ]
}

Then the part the operator actually asked for. The agent submitted that body with mode=VALIDATION_PREVIEW, read the returned issues array, and refused to go live until a human approved:

import requests

SPAPI = "https://sellingpartnerapi-na.amazon.com"
MARKETPLACE = "ATVPDKIKX0DER"
SELLER_ID = "A1EXAMPLESELLER"


def preview_patch(sku, body, token):
    response = requests.patch(
        f"{SPAPI}/listings/2021-08-01/items/{SELLER_ID}/{sku}",
        params={"marketplaceIds": MARKETPLACE, "mode": "VALIDATION_PREVIEW"},
        headers={"x-amz-access-token": token},
        json=body,
    )
    return response.json()


def submit_patch(sku, body, token):
    response = requests.patch(
        f"{SPAPI}/listings/2021-08-01/items/{SELLER_ID}/{sku}",
        params={"marketplaceIds": MARKETPLACE},
        headers={"x-amz-access-token": token},
        json=body,
    )
    response.raise_for_status()
    return response.json()


def run(sku, patch_body, token, approver):
    preview = preview_patch(sku, patch_body, token)
    errors = [i for i in preview.get("issues", []) if i.get("severity") == "ERROR"]
    if errors:
        return {"status": "blocked", "errors": errors}
    if not approver.approves(sku, patch_body, preview):
        return {"status": "declined"}
    return submit_patch(sku, patch_body, token)

The design choice that matters is that the preview call and the live call send the same body. The only difference is the mode query parameter. That means the thing the human approves is byte-for-byte the thing that ships, with no second translation step where a new error can creep in. The agent also kept the patch scoped to /attributes/bullet_point rather than rewriting the whole listing, so an approval reviewer reads one diff instead of auditing the entire item. And because the audit flagged the main image as a suppression risk, the agent explicitly declined to claim the copy fix would lift a suppression. It cannot, and saying so is part of being honest about what a patch can do.

The footnotes the agent surfaced unprompted

This is where retrieval grounding pulls away from fluent guessing. Without being asked, the agent attached the caveats an operator needs but rarely thinks to request:

Any one of these would have cost an afternoon to rediscover after a failed submission.

What happens next

Once VALIDATION_PREVIEW returns a clean issues array and the human approves, the agent resends the identical body without the mode parameter and the change goes live. It then watches the LISTINGS_ITEM_ISSUES_CHANGE notification stream to confirm the issue actually cleared, rather than assuming success. For the findings a text patch cannot solve, the path forks: the image flagged as a suppression risk is handed to the seeded image-regeneration workflow, and recurring audits are wired up as a scheduled Skill so the listing is re-checked after every catalog change instead of once a quarter. The same approval gate applies every time, which is the pattern explored in human approval for agent activation.

The full workflow runs through the Amazon Agent Data layer: Selling Partner MCP reads and previews listing changes, the Amazon Ads MCP can add Amazon Marketing Cloud (AMC) campaign-side performance context, Atlas grounds the catalog rules, and Skills keep every recurring patch behind a reviewable approval gate.

Why this matters

A foundation model can draft a better bullet point. What it cannot reliably do is read the live product-type schema, scope the edit to a JSON Patch that leaves the rest of the listing intact, run it through Amazon's own validation before committing, and tell you that the real problem was the image all along. That sequence is not model cleverness. It is a corpus of Amazon's own listing rules, indexed and addressable by an agent at the moment it is about to act, with a human holding the final yes.

If your agent can edit a live listing, it should be able to show you the diff first.

Next in the series: using your current product photos as seeds for OpenAI image generation to regenerate listing visuals that still pass Amazon's image requirements, with the same approve-before-publish gate sitting in front of every upload.

{"productType":"LUGGAGE","patches":[{"op":"replace","path":"/attributes/bullet_point","value":[{"value":"Hardside shell resists scuffs and cracking on checked flights","marketplace_id":"ATVPDKIKX0DER"},{"value":"Spinner wheels roll in four directions for easy gate turns","marketplace_id":"ATVPDKIKX0DER"}]}]}