amazon-listing

# Amazon — Listing CRUD (flat-file upload) > **PREREQUISITE:** read `../amazon-shared/SKILL.md` for the Ziniao > login challenge-loop (password / OTP / hosted-passkey), marketplace > TLDs, version-aware navigation (New Seller Central vs classic; > navigate by direct URL), and the capture rule (live data → > `/tmp/<task>/`, never `knowledge/`). That rule is for CAPTURES only — > do not make `/tmp` your working directory. The upload gate, the > reviewer gate and the accepted-spec library all read the TASK > WORKSPACE; the helpers and `parse-feedback` now write there whatever > your `$PWD` or `MARKER_DIR` is, but a review file you write yourself > still has to go where the gate names it (an absolute path). Amazon's **Add Products via Upload** takes a category **flat-file template** — a macro-enabled `.xlsm` whose `Template` sheet is a wide table (one column per attribute). One upload creates or edits a whole **variation family** (a Parent plus N colour/size Children) at once. This is the batch equivalent of the per-SKU web wizard, and the default for anything touching more than one variant. Two references, load what the task needs: - **`references/template-round-trip.md`** — the download → inspect → fill → upload → read-feedback loop, the operation column (create/update/partialupdate/delete), and the parent-child cluster. Load for **any** listing CRUD. - **`references/1688-sourcing.md`** — turning a supplier link into a filled template: page extraction, local no-GPU OCR of detail images, AI-generated copy, the **bilingual review** step, and image handling. Load when the task starts from a **product link**. > **Before you finish — verify it's LIVE, not just uploaded.** A 0-error > processing report is necessary but NOT sufficient; the listing is only > done when Manage Inventory shows it live with a real ASIN (per the > `review:` block above). Run the DoD review loop > (`../amazon-shared/references/dod-review-loop.md`) with this skill's > `review.criteria` / `review.verify_by` and converge to `Status: ok` > before `set_task_result`. ## Start from the last spec Amazon ACCEPTED — never from scratch Before writing a spec, look in `store-data/<slug>/listing-specs/` for `<product_type>__<CC>.json`. It is the spec behind the last batch of this category that **Amazon accepted** on that marketplace — saved automatically by `parse-feedback --batch-id` at the moment the verdict came back clean. Copy its `spec`, change only what this listing changes (SKUs, ASIN pins, copy, price), and keep every other field as it is. This is not a nicety. The fields Amazon enforces on a create are flagged **"Conditionally Required"** in the template (53 in one apparel template), so nothing warns about them locally — Amazon rejects them one feed at a time, 30–60 minutes per round. Two days running, the first create of a known product failed on exactly the fields the previous run's accepted spec already carried (style, special size, outer material, list price, package-dimension units), because that spec had died with its task. `fill` now names every field the accepted spec set that yours leaves empty; treat that warning as the rejection you have not waited for yet. No entry for your marketplace? Another marketplace's entry for the same product type is the next-best reference — the attribute set is the category's, not the storefront's. ## Work it like a human: upload → read the report → fix → repeat The template, its required fields, valid values, and even the upload mechanics **change per product type and over time**. Do not follow a fixed recipe from memory. Run the loop a human runs: 1. **Download a FRESH template** for the exact product type — Amazon's own error messages say "download the latest template". Never reuse a stale one. 2. **`inspect` it.** The field set / required fields / valid values for THIS category are the ground truth, not this doc. 3. **Fill, upload, then download the processing report** and run `parse-feedback REPORT.xlsm`. It reads the summary tables **and the per-cell comments (批注) on the report's `Template` tab** — where Amazon writes the precise, field-level verdict per SKU — and prints `sku=… field=… : MESSAGE`. 4. **For each ERROR line, fix exactly the field it names** — set it to a value from the template's own valid set (`inspect --field NAME`). Do not reinterpret or theorise a root cause; act on the report's words. (If a WARNING names a key defining attribute like material/pattern, fix it too — that's often what unblocks new-ASIN creation.) 5. **Re-upload and repeat until only expected noise remains** (see the main-image rule below). 6. **Final verify — the two sources of truth, not the feed count:** the **downloaded report** shows 0 blocking errors, AND the **Manage Inventory page** shows the family (parent's "Variations (N)", each child a real ASIN — not `-` — with title / description / bullets). The fixes listed below are **examples this loop surfaced on real templates** — priors that speed up diagnosis, not a checklist that replaces reading the actual report. ### Verification: trust inventory, not the feed count > **First, prove WHICH marketplace you are looking at — every other > reading is worthless without it.** A seller-central page renders the > marketplace the SESSION is on, whatever the URL subdomain says, so > "the `.ae` inventory page shows the family" is not evidence that AE > has it. Read the id, not a label: `js("return ue_mid")` returns the > live marketplace id (`A17E79C6D8DWNP` = SA, `A2VIGQ35RCS4UG` = AE …, > the full table is `marketplace_ids.py`), identical in every console > language. Do this on EVERY verification read, and quote the id in the > result — a family reported live on the wrong storefront is worse than > an unverified one, because it closes the loop on a lie. Observed > live: an AE-stamped upload landed in SA's upload history, and both > marketplaces were then "verified" off pages that were never the > marketplace claimed. The report's "records processed / 0 errors" means the **feed was accepted**, not that a live listing exists. A record *with* errors can still create an incomplete stub; a clean feed can leave a suppressed listing. **Always confirm on Manage Inventory, with `bh_listing_status.py`** (step 4 of the helper block below): it returns each SKU's ASIN off the page's own `div[data-sku]` rows, proves the marketplace by `ue_mid`, and names the SKUs that are not there. Confirm every SKU has the ASIN you meant, and for a family that the parent row (the one with `offer_cell: false`) carries the family's parent ASIN. `skucentral?mSku=` is not a verification surface: it renders empty in this console. > **"Missing Information / ASIN -" is usually NOT a failure — don't > thrash.** Two benign causes, and re-uploading fixes neither: > 1. **ASINs mint asynchronously.** A just-submitted family can show > `ASIN -` / a "Complete drafts → Submitted: Provide missing > information" entry for **10–30 minutes** while Amazon mints the > ASINs. Re-check Manage Inventory later — the parent flips to > `Variations (N)` with real child ASINs on its own. Do NOT re-upload > (that just spawns duplicate batches). > 2. **Only the main image is missing.** We intentionally don't upload > images, so a no-image product parks in "provide missing information" > for the image alone. **That is an acceptable DONE state** — the > seller adds the image later. The listing is **finished** once Manage > Inventory shows it with the variation relationship (`Variations (N)`), > real child ASINs, and correct **title / price / bullets**; a blank > image does not block "done". Only treat it as unfinished if the > processing report names a **non-image** blocking error. > **Do NOT re-upload just because Check Upload Status shows "N/A".** After > a submit, the batch's "SKUs successful / N/A" column stays `N/A` for > minutes (and CREATE/DELETE feeds can sit at N/A a long time) — that is > **normal, not a failure**, and the widget's shadow-root text may even > read "File not uploaded" on a submit that *did* go through. Re-uploading > on N/A just creates duplicate batches and wastes the run. Once you have > a batch reference_id, the upload was accepted: **go straight to Manage > Inventory** (search your SKU prefix) to verify the family is live — > that is the source of truth, not the feed status. Only re-upload if the > **downloaded processing report** names a real per-SKU error to fix. > > **A slow queue says NOTHING about your file, so do not "test" theories > against it.** Latency is not evidence: Amazon accepted the file the > moment it gave you a reference_id, and a CREATE feed submitted right > after a DELETE on the same SKUs is the slowest case there is — 30+ > minutes at N/A is ordinary. While a batch is pending the only legal > moves are **wait** and **check Manage Inventory**. Do not rewrite the > spec, and above all **do not remove an ASIN pin to see whether the pin > was the problem** — an unpinned create mints a new ASIN, so that > "test" destroys the very thing you were waiting to restore, and the > stall told you nothing about the pin either way. Observed live: an > agent 35 minutes into a pinned rebuild started proposing exactly that. > If you genuinely need to know why, wait for the processing report and > read what Amazon says; `fill` will refuse to drop the pin for you. ### Priors that recur across categories - **Upload a tab-delimited `.txt`, not the `.xlsm`.** `fill` writes the `.txt` next to the `.xlsm` for you — upload that. An openpyxl-saved `.xlsm` triggers a **90502 FATAL** ("worksheet template type not supported for Excel upload"). - **`fill --out` into the store downloads dir** (`~/.vibe-seller/downloads/<slug>/`), not `/tmp` — the browser must read the file to attach it (see `browser-harness` § "Uploading a file"). - **Submit is TWO clicks; the "network error" banner is a red herring.** On the unified upload page the 1st **Submit products** only fires `introspect-feed` (file-type detection → "Automatically detected" banner); a 2nd click actually posts the feed (URL gains `reference_id=`). The red "Sorry! There's a network error" toast shows even when introspect returned 200 — do NOT re-upload on it. See `references/template-round-trip.md` § 4. - **"1/N — parent created, children failed" is a CONTENT rejection, not a browser bug.** The file uploaded fine (it reached validation); download the Processing Summary and `parse-feedback` it for the per-child reason, then fix + re-upload the children. Never thrash on the upload widget. - **Children are NOT minimal.** Each child needs the full required set its category asks for (e.g. `item_name`, `target_gender`, `age_range_description`, and any compound-attribute sub-fields), plus its differentiator + offer — not just `parent_sku` + colour. - **"Required" is a guide, not an absolute — fill what you can, defer what you can't.** For each required-field error the report names, supply a sensible value: pick from the template's valid set (material, weave, size type, package dimension/weight units), set `list_price` = your price, `model_name` = the SKU/title. For a **new ASIN** with no GTIN, set the product-id **type** to `GTIN Exempt` (unified) / leave the id blank + set brand (legacy) if the brand is exempt. A few are genuinely deferrable — a real **main image** you don't have (18320) is added later and does NOT block creation. Don't stall the whole family on one attribute you can't provide; create with what you have and let the seller finish image/GTIN afterwards. - **Enum case is exact** (`UAE/KSA`, not `uae/ksa`). `fill` canonicalises a value to the template's own casing when the field has a valid set. - **Compound attributes come as a set** — e.g. Apparel Size needs `apparel_size_class` + `apparel_size_system` + `apparel_body_type` + `apparel_height_type` together; a partial set errors (99001/99022). - **Don't fight the marketplace checkboxes in the generator** — just make sure your **target** marketplace is ticked and Generate; do NOT try to uncheck the others. A bundled multi-marketplace template is fine (`fill` routes offer + quantity to your target's block); the store `kat-checkbox` toggles are unreliable and unchecking buys nothing but a stuck run. - **Main image is not required by default** — we do **not** upload images from here (the seller adds them separately). So a `18320` ("main image is missing") error is *expected noise*, not a blocker; don't chase it, and don't hotlink a supplier CDN URL into `main_image_url` (Amazon can't fetch a referer-protected 1688/alibaba URL anyway). "Done" = every error resolved **except** the image one — and that means **`parse-feedback` the report, not eyeball inventory**. A record can post as **SUCCESS (OTHER)** ("Action required", 0 successful): it *appears* in inventory but carries an unresolved, fixable error — e.g. **100476** ("Provide an Item Name ≤75 chars to use Item Highlights") when `title_differentiation` (Item Highlight) was filled on a long-title item. That is **NOT done**: fix the exact field the report names (Item Highlight is optional — clear it; the colour belongs in `color_name`) and re-upload. Only 18320 is a legit deferral. - **When the image is the only remaining error, report it as image-deferred, not "live".** A SUCCESS (OTHER) whose sole error is the missing main image ("submit a compliant image to lift the suppression") means the SKU is created + priced + stocked but **search-suppressed** — not buyable or discoverable until the seller adds an image. That is the accepted deferred done-state; report it as such (e.g. "N children created, linked, priced, stocked — suppressed pending main image, seller adds it to go live") rather than "live" or "done". The Manage Inventory row reads "Search suppressed" / "No image available" and the upload feed reads 0/N successful — expected for this state, not a failure to re-upload over. - **A buyable child that `8560`s ("doesn't match any ASINs … include standard_product_id")** — Amazon is refusing to *mint a new ASIN* for it. Two cases, decided by whether that child's ASIN already exists: - **ASIN already exists** (you're re-submitting, or a prior create left a catalog ASIN — note a `delete` removes your SKU/offer but **not** the catalog ASIN): don't try to create — **match** it. Set `operation: update`, `external_product_id` = the existing ASIN, `external_product_id_type: asin`. This is the reliable fix and what resolves a variation child that won't join its family. - **Genuinely new ASIN, GTIN-exempt brand** (leave `external_product_id` blank): the exemption alone is not enough — the report also warns which **key defining attributes are missing** (e.g. `material_type`, `pattern_name`); fill exactly those from the template's valid values so the ASIN can be minted. Either way, set `update_delete` on **every** row including children — never leave a child's operation blank. - **Offer/price is per-marketplace — set `our_price` + a top-level `marketplace`, don't hand-pick the column.** A multi-marketplace template has one `purchasable_offer[marketplace_id=<MKT>]` block per marketplace and marks the account's *home* marketplace's block Required — so hand-picking a column silently puts the price in the wrong marketplace, creating an ASIN with **no live offer** ("Missing offer", never live) even though the feed says success. Instead give the spec a top-level `"marketplace": "<CC>"` (the country you're listing on) and a bare `"our_price"` **and bare `"quantity"`** on each child; `fill` routes BOTH to that marketplace's block. **Stock is per-marketplace too, and it is NOT bracketed like the price** — each `fulfillment_availability#N` group is tied by *position* to one marketplace's offer block, so `#1` is a *different* marketplace than you may think. Never hand-pick a `fulfillment_availability#N.quantity` column; use the bare `quantity` and let `fill` pick the group adjacent to the target offer (it also normalises a wrong-index `fulfillment_availability#k.*` to the right one). Putting stock on the wrong group = an offer with no stock = never live. **Verify it in THAT marketplace's Pricing view** — the feed "N/N successful" count does not reflect price, and quantity can apply while price shows `--` if you set a different marketplace's column. - **A multi-marketplace account's template bundles every marketplace's offer columns** (e.g. a Europe account yields both SA + AE columns even when you select one) — a truly single-country template may not be downloadable there. "Clean single-country" then means: fill only the intended marketplace's offer block, leave the others blank. ## Relisting the same product on another marketplace (share the ASIN) When a product already lives on one marketplace (say SA) and the user wants it "the same" on another (say AE), the default intent is the **same ASIN on both**. Amazon pools ratings/reviews by ASIN, so minting a *new* ASIN forks the reviews and restarts the new marketplace at zero stars — for the same physical product that is almost never what's wanted. Only create a new ASIN when the user explicitly asks for a separate listing, or when the account's marketplaces are on genuinely separate catalogs (see below). **New ASINs AND the same children on both marketplaces is not a contradiction — it is a sequence.** When the user wants Amazon to mint fresh ASINs for a family that must match across two marketplaces, create on ONE marketplace first with `mint_new_asin`, wait for its report, read the ASINs it minted with `bh_listing_status.py`, and only then create on the second marketplace pinned to exactly those. Never mint on both (two different ASINs), and never upload the second before the first's new ASINs are read: on a unified account a second mint for the same SKU re-points it account-wide. Re-pinning to the family's OLD ASINs is a different answer to a different request -- one run did that when told "let Amazon mint new ones", because it saw the two asks as incompatible. If the request is ambiguous about new-vs-existing ASINs, ask. Make the match **proactively** — don't submit a blind create and wait for an `8560` to fix reactively: 1. **Get the source ASINs — one helper call per marketplace.** Map every SKU (parent + each child) to the ASIN it has on the SOURCE marketplace, and see what the TARGET already holds, before you plan a create or a delete: `SKUS=<parent>,<child-1>,... SC_HOST=sellercentral.amazon.<tld> browser-use < $S/bh_listing_status.py` (run it once with the source tld, once with the target's). Manage Inventory's search view collapses a family to its parent row, and probing it by hand — clicks, internal endpoints, public product pages — cost one run ten minutes before it fell back on ASINs remembered from an earlier task. A public product page proves an ASIN exists, never which SKU is on it. Reuse the **same SKUs** on the target marketplace; same SKU keeps it idempotent. 2. **Do the WHOLE target flow on the target marketplace's own subdomain — a create/update is marketplace-scoped. A DELETE IS NOT:** on a unified account it removes the SKU from every marketplace it sells on (an AE-only delete took the same three SKUs off SA too, while the AE rebuild that followed restored only AE). `fill` refuses a delete on a multi-marketplace template unless the spec says `"delete_everywhere": true` -- say it only when the user wants the SKU gone everywhere. To change ONE storefront's ASIN for a SKU, there is no delete-and-recreate route that leaves the other storefront alone: stop and ask the user. A flat-file upload applies to the marketplace of the `sellercentral.amazon.<tld>` you're on, regardless of the offer columns in the file; a `.sa` upload lands on SA even when the account context shows the target. So for AE, run template download +