amazon-seller-agent

name	amazon-seller-agent
version	0.1.0
description	Enables end-to-end operation of an Amazon seller account via the SP-API—including listing creation, publishing, reconciliation, variation family merging, bulk title updates, A+ content creation and submission—derived from running these against a live seller account. Use when the task involves Amazon Seller APIs (SP-API), Listings Items, A+ Content, variation families, bulk listings, POD fulfillment automation (Printify/Printful integration), post-listing verification/reconciliation, or diagnosing silent failures where "submission succeeded but items aren't live." Also used to determine if a listing action actually succeeded or just returned a favorable receipt.

Amazon Seller Agent

Production-tested methodology and operational reference for an agent that operates an Amazon seller account. This skill carries the procedures, checks and failure modes; the pipeline scripts themselves are not bundled here.

This is not "using AI to write listing copy"—the agent uses its own token, creates products, publishes them, waits for Amazon approval, independently re-pulls live data for verification, merges scattered child ASINs into variation families, updates titles per SKU, creates A+ content for review, and self-diagnoses submission failures using error codes before retrying.

Operational scale: batches of a few dozen designs each, tens of thousands of SKUs created within days. One job retitled 25,000+ live SKUs in a single pass, zero failures.

---

🔴 Read this first — the failure modes the API reference does not cover

90% of failures in this system produce no error.

Systems like Amazon and Printify fail silently: receipts are green, exit codes are 0, progress bars proceed, but nothing actually went live. The first principle of this skill is:

Your check must look at an artifact that only exists once this step succeeded — never at something that was already there.

Three prohibitions (each learned from real incidents, see references/06-silent-failures.md):

1. Do not assume "no bad news" means success — Absence of 🔴 in output does not equal success; the error message might just not contain the word you grep for.
2. Do not assume "a related thing exists" means completion — A crash midway can leave a partial artifact.
3. Verify with positive counts — Count the number of result lines, files, or completion log messages.

Verification always independently re-pulls live data; never trust submission receipts.

---

Quick Start

1. Credentials

cp scripts/env.example ~/.config/amazon/spapi.env
chmod 600 ~/.config/amazon/spapi.env

Three required values plus the marketplace (see references/01-credentials.md for setup): LWA_CLIENT_ID / LWA_CLIENT_SECRET / LWA_REFRESH_TOKEN / SPAPI_MARKETPLACE_ID

--whoami falls back to the region's primary marketplace if the last one is unset, so the probe can still run and tell you what your account sells in. Production code should always set it explicitly.

🔴 SP-API does not require SigV4: Use LWA refresh token to get an access token directly; no AWS IAM signing needed. Many old tutorials still teach SigV4—that's outdated. 🔴 Access tokens expire in 1 hour: For long tasks exceeding 45 minutes, you must auto-renew; otherwise the second half will get all 403s while your progress bar shows normal.

2. Smoke Test

python3 scripts/probe.py --whoami

Do not proceed if you cannot retrieve seller account info.

3. Run a Pipeline

See the routing table below. Get one item all the way through before running a batch. A hard lesson behind this: 4,000 quota calls were spent before anyone noticed only 14% of the results were usable.

---

Three Blocks

The work has three parts, and they fail in different ways.

Block	What it answers	Chapters
Research	What is already sold, what is searched for, where those do not line up	10-research.md
Listing	Getting a product from designed to purchasable, and proving which ones got there	01–09
Operating	What it earns, what sold, what it costs, whether the account is in trouble	11-operations.md

Underneath all three: 12-discipline.md — how to know a run actually did the work. That chapter has no API in it and is the one that transfers to other platforms.

⚠️ Research measures; it does not choose. Nothing here decides what to sell.

---

Pipeline Routing Table

Listing is not one action; it is twelve steps. Each step has its own verification criteria.

Step	What	Key Criteria	Deep Dive
① Design Assets	Generate / prepare images	Decodable + correct pixel dimensions (not file size)	references/02-assets.md
② Upscale	Print resolution	Flat color → NEAREST, gradients → ESRGAN	references/02-assets.md
③ Copy	Title / bullet / description	Title globally unique (fail-closed)	references/07-copy.md
④ Listing Creation	Push to POD platform	Ledger positive count matches	references/03-listing.md
⑤ Listing Verification	Independent re-pull check	Six items compared one-by-one against live truth	references/03-listing.md
⑥ Publish	Publish to Amazon	Count by number of products, not designs	references/03-listing.md
⑦ Approval	Wait for Amazon to assign ASIN	Progress indicator, not verification	references/05-errors.md
⑧ Reconciliation	Expected N vs actual	Discrepancy must be explainable	references/03-listing.md
⑨ Merge	Scattered SKUs → variation family	Child parent_sku == anchor	references/04-variations.md
⑩ Update Titles	Each child writes its own variant	Read from buyer side, not seller side	references/04-variations.md
⑪ Convergence Verification	Lag count reaches zero	Count unapproved / approved-but-unpositioned separately	references/04-variations.md
⑫ A+ Content	Create doc → attach → submit	Attach to every ASIN it should show on	references/08-aplus.md

---

Find Chapter by Task

Task	Read This
Credentials, token refresh, rate-limit backoff	references/01-credentials.md
Design specs, print resolution, upload size limits	references/02-assets.md
Full listing/publish/reconciliation flow	references/03-listing.md
Variation families: merge, title updates, parent-child	references/04-variations.md
Full error code table + handling	references/05-errors.md
🔴 Silent failure checklist — read before writing any write path	references/06-silent-failures.md
Copy guardrails: trademark / IP / prohibited terms	references/07-copy.md
A+ content full flow + 8 pitfalls	references/08-aplus.md
POD platform integration (Printify)	references/09-pod-integration.md
Research: supply breadth, search terms, rebuilding a leaderboard	references/10-research.md
Operating: reports, traffic, orders, repricing, account health	references/11-operations.md
🔴 Engineering discipline (transfers to any platform)	references/12-discipline.md

---

Five Hard Constraints (Violate Any = Problems)

1. Run only one listing process and one publish process at a time — Parallel runs hit 429s, and the command returns 0; the outer chain only checks exit codes and assumes success.
2. Never delete and recreate — Real case: deletion voided a GTIN exemption. When a SKU is stuck, read its issue code first: some codes mean "fix the cause and resubmit in place", others mean "it is in manual review, resubmitting makes it worse". Never resubmit blindly.
3. Never republish a live product — It pushes stale data from the POD backend back over values that were edited by hand.
4. After changing a value, grep -rn '<old_value>' the entire codebase — A single documentation source ≠ single source of truth in code (once, after a price decision, four docs were updated but the listing script was missed, nearly creating 81 loss-making products).
5. New guardrails must be tested with negative samples — Passing a positive sample proves nothing; you must create a scenario that actually triggers the guardrail (an empty input "pass" has no proof value).

---

Honest Boundaries of This System

• It solves listing, not traffic. Volume and sales correlation is weak—a test with 422 sellers showed r² = 0.023; volume explains only 2% of sales variation. Expecting "more listings = more profit" will disappoint.
• Its value is reliable agent operation of production systems. Repetitive, error-prone actions like listing, price updates, title changes, A+ creation, and verification run at near-zero marginal cost after the first run.
• Product selection and design are still human jobs. Deliberately out of scope. The research chapter measures supply and demand; the decision is yours.
• Not covered at all: advertising (no ads API here), inventory planning, appeals and account-health remediation. 11-operations.md reads the metrics that suspend accounts; it does not argue with Amazon about them.