| 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):
- 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.
- Do not assume "a related thing exists" means completion — A crash midway can leave a partial artifact.
- 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)
- 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.
- 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.
- Never republish a live product — It pushes stale data from the POD backend back over values that were edited by hand.
- 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).
- 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.
