cx-listing-playbook 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # cx-listing-playbook
2
2
 
3
- A [pi](https://pi.dev) package for the work on an Amazon listing: how it performs and why, a log of each change, and how to judge whether a change worked. It is written for the assistant in a [ComChatX](https://comchatx.com) seller's box, and reads the seller's Amazon account through the box's `cx` command.
3
+ A [pi](https://pi.dev) package for the work on an Amazon listing: creating it, how it performs and why, a log of each change, and how to judge whether a change worked. It is written for the assistant in a [ComChatX](https://comchatx.com) seller's box, and reads the seller's Amazon account through the box's `cx` command.
4
4
 
5
- It is text and one script. Every sentence of the skills ends with the research item it rests on, and the research is in [`research/`](research/README.md).
5
+ It is text and one script. Its changes are in [CHANGELOG.md](CHANGELOG.md). Every sentence of the skills ends with the research item it rests on, and the research is in [`research/`](research/README.md).
6
6
 
7
7
  ## What it holds
8
8
 
@@ -10,7 +10,9 @@ It is text and one script. Every sentence of the skills ends with the research i
10
10
  |---|---|
11
11
  | `skills/listing-review` | The funnel and which element serves each stage, what Amazon's own answers show about a listing, the signals that something changed, which file carries each figure, how a write is validated (`references/writing.md`), and `scripts/report.sh` |
12
12
  | `skills/listing-change-log` | One file per listing change: before, after, what was expected and from which file, the words bet on, the seller's decision, the request as it would be sent, Amazon's receipt id and the observation window |
13
+ | `skills/listing-create` | Creating a listing in the stores the seller names: new item or existing ASIN, the product type and each store's schema, identity, the request built from the seller's data, the preview (sent as a read, since it persists nothing), the write on the seller's word, the read-back until buyable and discoverable, and variation families |
13
14
  | `skills/effect-review` | Experiments, baseline and observation windows, controls, confounders, and the three verdicts: held, not held, cannot tell |
15
+ | `prompts/listing-create.md` | `/listing-create <marketplaces> <your words, and where the product's data is>`: hands the seller's words to cx, e.g. `/listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货` |
14
16
  | `prompts/listing-review.md` | `/listing-review <ASIN>`: the listing and its issues, the market since last time, a proposal with its reasons |
15
17
  | `prompts/listing-watch.md` | `/listing-watch <ASIN> <your words>`: writes the standing instruction for that listing from the seller's words, e.g. `/listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵` |
16
18
 
@@ -52,7 +54,7 @@ On ComChatX, a seller installs it from the Plugins page.
52
54
  ```bash
53
55
  npm ci
54
56
  npm run typecheck
55
- npm test # pi at the pin loads the package and expands both templates; every text line cites a research item;
57
+ npm test # pi at the pin loads the package and expands every template; every text line cites a research item;
56
58
  # the script runs against a stub cx
57
59
  ```
58
60
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cx-listing-playbook",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "A pi package for the work on an Amazon listing: how it performs and why, a log of each change, and how to judge one.",
5
5
  "license": "MIT",
6
6
  "author": "ComChatX",
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Create Amazon listings from your own words and your product's data — e.g. /listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货
3
+ argument-hint: "<marketplaces> <your words, and where the product's data is>"
4
+ ---
5
+ Create my listing in $1 from my words: ${@:2}
@@ -1,6 +1,6 @@
1
1
  # Research for cx-listing-playbook
2
2
 
3
- This directory is the research base for the pi package cx-listing-playbook: the skills listing-review (which carries references/writing.md), listing-change-log and effect-review, the script scripts/report.sh, and two templates, /listing-review and /listing-watch (which writes the standing instruction); every file here was read on 2026-10-14. Sources are weighed in this order and tagged by type: Amazon's own words first, tagged [official] (Seller Central help, SP-API docs and models, Amazon Ads, aboutamazon.com, sell.amazon.com, Amazon staff posts in Seller Forums; Keepa's own documentation and code, and regulators' pages, carry the same tag); then named practitioners and vendors, tagged [opinion]; then published research and Amazon Science, tagged [research]; the researching seat's own reasoning is tagged [seat], and no skill states a [seat] item as fact. Two limits were kept: no Amazon or Keepa API host was called (no `sellingpartnerapi-*`, no `api.keepa.com`; documentation pages only), and no seller data is held here (no store names, seller ids, real seller ASINs or store figures; `<ASIN>` and `<SKU>` stand in). Seller Central help pages were read through the help hub's own content call, as recorded in method/help-page-access.md, and the standing use of that call is for the office to rule.
3
+ This directory is the research base for the pi package cx-listing-playbook: the skills listing-review (which carries references/writing.md), listing-change-log, effect-review and listing-create, the script scripts/report.sh, and three templates, /listing-review, /listing-watch (which writes the standing instruction) and /listing-create; every file here was read on 2026-10-14, except method/listing-create.md, read on 2026-10-27. Sources are weighed in this order and tagged by type: Amazon's own words first, tagged [official] (Seller Central help, SP-API docs and models, Amazon Ads, aboutamazon.com, sell.amazon.com, Amazon staff posts in Seller Forums; Keepa's own documentation and code, and regulators' pages, carry the same tag); then named practitioners and vendors, tagged [opinion]; then published research and Amazon Science, tagged [research]; the researching seat's own reasoning is tagged [seat], and no skill states a [seat] item as fact. Two limits were kept: no Amazon or Keepa API host was called (no `sellingpartnerapi-*`, no `api.keepa.com`; documentation pages only), and no seller data is held here (no store names, seller ids, real seller ASINs or store figures; `<ASIN>` and `<SKU>` stand in). Seller Central help pages were read through the help hub's own content call, as recorded in method/help-page-access.md, and the standing use of that call is for the office to rule.
4
4
 
5
5
  ## How to read this
6
6
 
@@ -60,6 +60,7 @@ Every research file has one layout: what it covers; Amazon's rules; what practit
60
60
  | funnel-and-search.md | the funnel, its gates, which element serves which stage, Amazon search's own words | all | listing-review |
61
61
  | help-page-access.md | how Seller Central help pages were read, how to cite them, and what each captured page says, by owning file | none (method) | research upkeep; listing-review; writing.md |
62
62
  | (not in this repository) | 54 dated text captures of Seller Central help pages, each named `<page id>-v<version>`: Amazon's own text, so the office keeps them and this repository cites them as `capture <id>-v<n>` | none (evidence) | research upkeep |
63
+ | listing-create.md | creating a listing: stores, new item against existing ASIN, product type and schema, identity and GTIN exemption, the request, variations, preview, write, read-back, sandbox, Build International Listings | none (write path) | listing-create |
63
64
  | listing-policies.md | claims, restricted words, regulators' rules, post-acceptance issues | all (policy gate) | writing.md; listing-change-log |
64
65
  | listing-writes.md | schema conformance, preview, patch and put, feeds, deletes, recording a write | none (write path) | writing.md; listing-change-log |
65
66
  | report-lifecycle.md | report and Data Kiosk lifecycles: create, poll, terminal statuses, documents, pagination, schedules, cancels, rate limits, landed receipts | none (data path) | scripts/report.sh; effect-review |
@@ -379,7 +380,7 @@ Each position is one sentence, followed by the P-ids that carry it and the names
379
380
  - **S24.** A bulk change goes as a `JSON_LISTINGS_FEED` through `createFeedDocument`, `createFeed`, `getFeed` to a terminal status and `getFeedDocument`, one store per feed. — P-listing-writes-19, 20, 21; P-seller-central-only-tools-11. [official] Submit a feed; listings-feed-schema-v2.json; Deprecation of Feeds API support for XML and Flat File Listings Feeds.
380
381
  - **S25.** The FBA Fee Preview report is read within the request limit the FBA Reports page states. — P-inventory-and-fulfillment-20. [official] Fulfillment by Amazon (FBA) Reports.
381
382
 
382
- ### The two templates and the standing instruction
383
+ ### The templates and the standing instruction
383
384
 
384
385
  - **T1.** /listing-watch writes a standing instruction that states what to watch (the ASINs, the competitor set, the trigger families), how often, the seller's own thresholds, when to speak and when to stay quiet, and where to report, with no default threshold supplied. — P-triggers-13. [opinion] Jungle Scout, Amazon Product Alerts; Helium 10, Alerts; Google SRE ch. 6.
385
386
  - **T2.** Between summaries cx speaks only for a new signal the seller can act on (a suppression, a lost Featured Offer, a stock-out, a content change nobody on the seller's side made), and everything else goes into the scheduled summary. — P-triggers-14. [official] Manage Listings Issues. [opinion] Google SRE ch. 6.
@@ -401,6 +402,19 @@ Each position is one sentence, followed by the P-ids that carry it and the names
401
402
  - **T18.** A help page is cited by its title, canonical id, version and read date, read first from its capture under the office's capture folder (outside this repository), and cx does not depend on the undocumented content call at run time. — P-help-page-access-1, 2, 3, 7. [official] the captured pages under the office's capture folder (outside this repository)
402
403
  - **T19.** /listing-review starts from the trigger or the seller's question, runs the gates (L2 to L10), names the stage (L1), and only then reads the elements for that stage (L13). — P-funnel-and-search-1, 3; P-triggers-1, 2. [official] My ASIN is unsearchable; Manage Listings Issues.
403
404
 
405
+ ### listing-create
406
+
407
+ - **R1.** The stores a creation goes to are the ones the seller names, each checked in `getMarketplaceParticipations`, which gives that store's language and currency. — P-listing-create-1; P-sp-api-access-1. [official] sellers.json; Get the market participation of a seller.
408
+ - **R2.** A catalog search by identifier sorts the product into an existing ASIN (offer-only listing, `PRODUCT` with `LISTING_OFFER_ONLY`, after its restrictions read) or a new item with product facts. — P-listing-create-2, 3, 22. [official] Building Listings Management Workflows Guide; Listings APIs FAQ.
409
+ - **R3.** A new item's product type comes from `searchDefinitionsProductTypes`, and its schema is read separately for each store, with `requirements`, `sellerId` and `parentageLevel`. That schema's keywords decide what each value must look like. — P-listing-create-4, 5, 6. [official] definitionsProductTypes_2020-09-01.json; Retrieve a Product Type Definition; Meta-Schema (v1).
410
+ - **R4.** Identity is a GTIN the seller owns or is licensed to use, or an approved exemption with the brand spelled exactly as approved. A Brand Registry brand takes the brand's own account or one the brand authorised. — P-listing-create-9, 10, 11. [official] Product detail page rules (G200390640 v21); Listings APIs FAQ; How to create Amazon product listings.
411
+ - **R5.** A creation is one put per store, in that store's language and currency. It carries images as locations Amazon fetches (a new object key for new content in private S3), the fulfilment record for MFN or FBA, and the compliance attributes the store's schema names, all filled from the seller's own data. — P-listing-create-7, 8, 12, 13, 14, 15. [official] listingsItems_2021-08-01.json; Submit Listings data; Submit media attributes; Manage purchasable offer; Manage Amazon Haul … Multiple-Fulfillment Use Cases.
412
+ - **R6.** A preview is the same put with `mode=VALIDATION_PREVIEW`. It persists nothing and answers `VALID` or `INVALID`, and its issues name any required attribute the data left empty. — P-listing-create-17; P-listing-writes-5. [official] Preview errors before creating or fully updating a listing; Listings Items API Issues Troubleshooting.
413
+ - **R7.** A family is written parent first, then each child with the relationship and the parent's theme. — P-listing-create-16. [official] Building Listings Management Workflows Guide; Submit Listings data.
414
+ - **R8.** `ACCEPTED` starts processing. The creation is done when a read-back shows an ASIN, `BUYABLE` and `DISCOVERABLE`, and no `ERROR` issue; an empty summary is, in the FAQ's words, a submission that failed and did not match an ASIN, and Amazon states no time for any of this. — P-listing-create-18, 19. [official] Listings APIs FAQ; listingsItems_2021-08-01.json.
415
+ - **R9.** A static sandbox answer proves only the request's path, signing and shape. Build International Listings is a Seller Central tool, so it is not part of this path. A creation is logged as a change with an empty before. — P-listing-create-20, 21, 23. [official] Selling Partner API Sandbox; Build International Listings (G202121570 v14).
416
+ - **R10.** Each conflict issue is answered as its own text says: `4005011` change the value or contact Amazon, `4005033` revert and resubmit, `101165` make the identifiers unique and resubmit, with support where the catalog itself is wrong. — P-listing-create-24. [official] Listings Items API Issues Troubleshooting.
417
+
404
418
  ## Where the files disagreed, and what won
405
419
 
406
420
  - **Help pages called unreachable.** Files that called a page unreachable or behind sign-in were stale wherever a capture exists under the office's capture folder (outside this repository); the capture won (P-help-page-access-3).
@@ -515,13 +529,15 @@ Every figure below was read on 2026-10-14 on the page named. No skill states the
515
529
  | Account Health Assurance window: 72 hours on one page, 13 days on another | Account Health Assurance FAQ; as cited in account-health.md |
516
530
  | Store moderation up to 24 hours | stores-best-practices, as cited in brand-story-and-store.md |
517
531
  | Keepa: variation-specific rating count frozen since 2025-04-09; price slots changed definition on 2026-02-23 | Keepa Product Object |
532
+ | New listings: up to 24 hours for an image to appear; `getListingsItem` reflects state in 1–5 minutes and notifications in 15–20; `putListingsItem` 5 a second (burst 5 on the page, 10 in the model); validation previews 20 a second per application (patch row only); definitions 5 a second, burst 10; `getMarketplaceParticipations` 0.016 a second, burst 15; schema links valid seven days; no stated time for ASIN assignment | Product image guide (G1881 v28); Add product images and video (G200216080 v15); Listings APIs FAQ; Listings Items API Rate Limits; listingsItems_2021-08-01.json; definitionsProductTypes_2020-09-01.json; sellers.json; Retrieve a Product Type Definition (read 2026-10-27, as cited in method/listing-create.md) |
533
+ | Seller Central's Add a Product form: up to five bullets and nine photos | How to create Amazon product listings (sell.amazon.com, Apr 29, 2026) |
518
534
 
519
535
  ## Open questions
520
536
 
521
537
  ### For Jack's word
522
538
 
523
539
  - **The content call.** May the help hub's undocumented content call have any standing use, at research or at run time? Until ruled, no further pages are fetched through it. (help-page-access OQ1; the office rules.)
524
- - **Is a preview a write?** Does `VALIDATION_PREVIEW` on a real store count as a write under "nothing sent without the seller's word", including previews for price, claim or title tests?
540
+ - **Is a preview a write?** Ruled by brief 2026-10-26-87: a preview (`putListingsItem` or `patchListingsItem` with `mode=VALIDATION_PREVIEW`) persists nothing (P-listing-writes-5), so it is sent as any read is; a write without the mode waits for the seller's word (R6, R8).
525
541
  - **Acceptable Use Policy.** How does AUP 4.3 bear on Keepa use and on recommending third-party tools?
526
542
  - **Brand Analytics terms.** May Brand Analytics figures be kept in change files and reports under the Brand Analytics Terms and Conditions (P-own-traffic-funnel-23)? (Jack, or counsel.)
527
543
  - **Selling Partner plugin.** Is the Selling Partner plugin in scope for the box?
@@ -620,12 +636,13 @@ Counts are rows of each file's *Pages read* table, so a page read by several fil
620
636
  | method/effect-measurement.md | 50 | 12 | 26 | 6 |
621
637
  | method/funnel-and-search.md | 89 | 12 | 12 | 9 |
622
638
  | method/help-page-access.md | 41 | 0 | 0 | 3 |
639
+ | method/listing-create.md | 30 | 0 | 0 | 2 |
623
640
  | method/listing-policies.md | 93 | 15 | 7 | 11 |
624
641
  | method/listing-writes.md | 79 | 8 | 3 | 2 |
625
642
  | method/report-lifecycle.md | 62 | 4 | 1 | 5 |
626
643
  | method/seller-central-only-tools.md | 51 | 7 | 2 | 3 |
627
644
  | method/sp-api-access.md | 40 | 2 | 0 | 6 |
628
645
  | method/triggers.md | 84 | 10 | 6 | 4 |
629
- | **total** | **2513** | **399** | **204** | **235** |
646
+ | **total** | **2543** | **399** | **204** | **237** |
630
647
 
631
- Distinct URLs on rows that were read (first URL per row): 1,663. The unreachable rows come to 166 distinct addresses not read by any other file. The office's capture folder (outside this repository) holds 54 dated captures of Seller Central help pages. The files hold about 897 position IDs across 19 angle, 10 element and 10 method files, merged into the 270 positions above.
648
+ Distinct URLs on rows that were read (first URL per row): 1,663. The unreachable rows come to 166 distinct addresses not read by any other file. The office's capture folder (outside this repository) holds 54 dated captures of Seller Central help pages. The files hold about 921 position IDs across 19 angle, 10 element and 11 method files, merged into the 280 positions above (method/listing-create.md's 24 into R1–R10, its 32 page rows counted in the table but not in the distinct-URL figure).
@@ -543,7 +543,7 @@ These hold at the level of mechanism. Every number below is located, not pinned.
543
543
  - **Amazon's view.** `getCatalogItem` on `<ASIN>` with `includedData=summaries,attributes,images,classifications,relationships,salesRanks,productTypes,identifiers`. Diff it field by field against the submitted attributes.
544
544
  - **Requirements.** `getDefinitionsProductType` for the listing's `productType`, store, `sellerId`, `requirements=LISTING` and the right `parentageLevel`. Read `maxLength` (and `maxUtf8ByteLength` where present) on `item_name`, `title_differentiation`, `bullet_point`, `product_description` and `generic_keyword`, the image attributes offered, required attributes, enums and conditionals, and keep the version and checksum. These are the binding figures wherever Amazon's help pages disagree with one another or with the schema.
545
545
  - **Eligibility, when relevant.** `getListingsRestrictions`.
546
- - **A preview, only with the seller's word.** `patchListingsItem` with `mode=VALIDATION_PREVIEW`. Then, after any real write, re-read `getListingsItem`.
546
+ - **A preview.** `patchListingsItem` with `mode=VALIDATION_PREVIEW`, sent as any read is, since it persists nothing (ruled by brief 2026-10-26-87). A write without the mode waits for the seller's word. Then, after any real write, re-read `getListingsItem`.
547
547
  - **Store-wide sweep.** `searchListingsItems` with `withIssueSeverity=ERROR`, or `withStatus=DISCOVERABLE&withoutStatus=BUYABLE`, and so on (cap 1,000). Or door.md's `createReport` / `getReport` / `getReportDocument` for `GET_MERCHANTS_LISTINGS_FYP_REPORT` and `GET_MERCHANT_LISTINGS_ALL_DATA`. Names, options and waits are door.md's.
548
548
  - **Rate headers.** `x-amzn-RateLimit-Limit` on every reply.
549
549
  - **Competitors' content.** The Keepa product fields listed above, from the Keepa skill. Changes are visible only as a diff between snapshots cx kept.
@@ -723,7 +723,7 @@ Reconciliation reads, 2026-10-14. Help-page captures were read from the office's
723
723
  - (Gap fill) A sweep over 1,000 matching SKUs: is it complete if sliced by `lastUpdatedAfter` / `lastUpdatedBefore` or `createdAfter` windows? Amazon's pages do not say.
724
724
  - Do the FYP report's "Reason" values map one-to-one to `issues[].code`, or are they a separate vocabulary?
725
725
  - After a 75-character AI rewrite, does `getCatalogItem` show the new name in `summaries.itemName`, in `attributes.item_name`, or in both? And does `BRANDED_ITEM_CONTENT_CHANGE` fire for it?
726
- - Does `patchListingsItem` with `VALIDATION_PREVIEW` count as a write under this line's "nothing sent without the seller's word" rule? It persists nothing but is a PATCH. This needs the office's ruling.
726
+ - Ruled (brief 2026-10-26-87): `patchListingsItem` or `putListingsItem` with `VALIDATION_PREVIEW` persists nothing (P-listing-writes-5), so it is sent as any read is; a write without the mode waits for the seller's word.
727
727
  - Should door.md carry the listing report names (`GET_MERCHANT_LISTINGS_ALL_DATA`, `GET_MERCHANTS_LISTINGS_FYP_REPORT`) with options and waits? It holds none today.
728
728
  - Can cx ever receive notifications (SQS/EventBridge)? Without a destination, every "watch" is a poll against rate limits.
729
729
  - How fresh are Keepa's content fields (`title`, `features`, `description`) relative to the live page? angles/competitor-set.md quotes Keepa's docs: "If our last update is older than ~1 hour, it will be automatically refreshed before being delivered." That bounds Keepa's own copy at request time; whether Keepa's copy matches what the detail page shows is still open.
@@ -0,0 +1,389 @@
1
+ # Creating a listing: the seller's stores, the product type, the schema, identity, the preview, the write and the read-back
2
+
3
+ Read 2026-10-27 by the research seat for brief 2026-10-26-87. Tags: [official] Amazon's own page, model or staff post; [opinion] a named practitioner or a seller's report; [research] published research; [seat] the seat's own reasoning, never a skill position.
4
+
5
+ ## What this covers
6
+
7
+ This file covers the path from a seller's new product data and the marketplaces they name to a listing that Amazon shows as buyable and discoverable. It has these parts:
8
+
9
+ - **Where the seller sells.** The stores from `getMarketplaceParticipations`, with each store's language and currency.
10
+ - **New item or existing item.** How Amazon tells a product it already has (an offer-only listing on that ASIN) from one it does not (a new item with product facts).
11
+ - **The product type and its schema.** `searchDefinitionsProductTypes` and `getDefinitionsProductType`, read for each store, and which schema keywords decide what a value must look like.
12
+ - **Product identity.** GTIN, UPC and EAN; the brand; Brand Registry; the GTIN exemption.
13
+ - **The request.** `putListingsItem` with `productType`, `requirements` and `attributes`, in each store's language and currency, with images, fulfilment, price and the compliance attributes the store's schema names.
14
+ - **Variations.** Parent first, then children, with relationship and theme.
15
+ - **The preview, the write and the read-back.** `mode=VALIDATION_PREVIEW`, the submission's `submissionId` and `status`, asynchronous issues, and `getListingsItem` until `BUYABLE` and `DISCOVERABLE`.
16
+ - **Build International Listings,** which is Seller Central's tool, not the API's.
17
+ - **The sandbox:** what a static sandbox answer proves and what it does not.
18
+
19
+ The file extends `research/method/listing-writes.md`, which covers the write side of an existing listing (the schema, patch and put, the preview, `ACCEPTED`, the Catalog view, deletes, feeds and stores). Where that file already holds a rule, this file names its P-id rather than restating it. It also leans on `research/angles/marketplaces-and-languages.md` (stores, language tags, GPSR), `research/elements/attributes-and-browse-nodes.md` (product type, compliance attributes, restrictions), `research/elements/variations.md` (families), `research/elements/images-and-video.md` (image rules), `research/method/sp-api-access.md` (participations, the seller id, roles) and `research/angles/brand-protection-and-catalog-contribution.md` (brand roles).
20
+
21
+ Sources, in order of weight:
22
+
23
+ - **Amazon's developer documentation**, fetched in `.md` form. The host `developer-docs.amazon.com` now answers 301 to `developer-docs.amazon`; the pages below are cited at the address they were read from. Each page's `updatedAt` is recorded in *Pages read*.
24
+ - **The OpenAPI models** in `amzn/selling-partner-api-models` at commit `3677bb9d96f4450e6843f1f8207005e925d5c867`, the commit the `cx-amazon-sp-api` door names (its `references/door.md`). Line references are to that commit.
25
+ - **Seller Central help pages**, read only from their 2026-10-14 captures under the office's capture folder (outside this repository). The help hub's content call was not used: the office has not ruled on it (`research/method/help-page-access.md`, open question 1). A help page with no capture is recorded as unread.
26
+ - **sell.amazon.com**, Amazon's seller site.
27
+ - **One Seller Forums post by an Amazon-named account and one GitHub issue answered by Amazon's Solutions Architect.**
28
+ - Practitioners where they add something.
29
+
30
+ No Amazon API host (`sellingpartnerapi-*`, `sandbox.sellingpartnerapi-*`) and no Keepa host was called. No seller data is here: `<sellerId>`, `<SKU>`, `<ASIN>` and `<marketplaceId>` stand in, and the marketplace id `ATVPDKIKX0DER` appears only as Amazon's own examples print it.
31
+
32
+ ## Amazon's own rules and guidance
33
+
34
+ ### A. Where the seller sells
35
+
36
+ 1. **RULE: the seller's stores.** `getMarketplaceParticipations` "Returns a list of marketplaces where the seller can list items and information about the seller's participation in those marketplaces." Each row carries `marketplace` (with `id`, `countryCode`, `defaultCurrencyCode`, `defaultLanguageCode`, `domainName`, `name`), `participation` (`isParticipating`: "If `true`, the seller participates in the marketplace"; `hasSuspendedListings`: "`true` if the seller Listing Status is set to Inactive") and `storeName`. The default rate is 0.016 requests a second, burst 15.
37
+ - The tutorial names the Selling Partner Insights role; Role Mappings (read 2026-10-14 in `research/method/sp-api-access.md`, A6) gives Product Listing or Selling Partner Insights, either being enough. The door's application holds Product Listing.
38
+ - The existing positions already say what cx does with this reply (P-sp-api-access-1, P-sp-api-access-14; P-marketplaces-and-languages-2).
39
+
40
+ [official] (sellers.json at the pin, `models/sellers-api-model/sellers.json`, definitions `MarketplaceParticipation`, `Participation`, `Marketplace`; Get the market participation of a seller, https://developer-docs.amazon/sp-api/docs/get-seller-market-participation.md, updatedAt 2026-09-09, read 2026-10-27)
41
+
42
+ 2. **RULE: one store per definition and per content write.** `getDefinitionsProductType`'s `marketplaceIds` "is limited to one marketplaceId at this time." The FAQ: "the data for each ASIN differs by Amazon store because countries have different data requirements specific to that Amazon store", and "Use the `marketplaceIds` filter in the Product Type Definitions API v2020-09-01 operations to get the Amazon store-specific requirements". The FAQ also answers "No" to a multi-store `JSON_LISTINGS_FEED`: the feed "and Listings Items API v2021-08-01 supports a single Amazon store per feed."
43
+ - `research/method/listing-writes.md` (P-listing-writes-22) already holds one store per content write, with the multi-store exception for `purchasable_offer` patches and deletes.
44
+
45
+ [official] (definitionsProductTypes_2020-09-01.json at the pin; Listings APIs FAQ, https://developer-docs.amazon/sp-api/docs/listings-apis-faq.md, updatedAt 2026-09-09, read 2026-10-27)
46
+
47
+ ### B. New item or existing item
48
+
49
+ 3. **RULE: Amazon's two create workflows, and how they are told apart.** The workflows guide has two sections, "List an item that does not already exist in the Amazon catalog" and "List an offer for an item that already exists in the Amazon catalog". Both start the same way:
50
+ - "Call the `searchCatalogItems` operation to search for existing items in the Amazon catalog by product identifiers (for example, UPC, EAN) or keywords. If an exact match is found, follow the steps in List an offer for an item that already exists … If an exact match is not found, continue to the next step."
51
+ - On several matches: "If multiple matches are found, inspect the returned items' attributes (product type, brand, title, parentage level) to identify the correct ASIN. Call the `getCatalogItem` operation for each ASIN to retrieve detailed attributes and validate which product matches your intended item before creating an offer."
52
+ - The FAQ says the same of an offer: "Before creating an offer for an ASIN, use the Catalog Items API to verify if the ASIN exists in Amazon's catalog for the specified Amazon store. If an exact match is found and a valid ASIN is returned, use the Listings Restrictions API to check if you are eligible to list that ASIN. Complete both steps before creating an offer-only listing."
53
+ - `searchCatalogItems` takes `identifiers` with `identifiersType` (`ASIN`, `EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `SKU`, `UPC`), or `keywords`, never both; `marketplaceIds` is required; `includedData` can name `attributes`, `classifications`, `dimensions`, `identifiers`, `images`, `productTypes`, `relationships`, `salesRanks`, `summaries` and `vendorDetails`. Its default rate is 2, burst 2.
54
+
55
+ [official] (Building Listings Management Workflows Guide, https://developer-docs.amazon/sp-api/docs/building-listings-management-workflows-guide.md, updatedAt 2026-09-24, read 2026-10-27; Listings APIs FAQ, as above; catalogItems_2022-04-01.json at the pin, `GET /catalog/2022-04-01/items`)
56
+
57
+ 4. **RULE: the offer-only path.** For an item Amazon has:
58
+ - "Call the `getListingsRestrictions` operation with the ASIN identifier to retrieve any eligibility requirements that must be met before listing an item in the applicable condition."
59
+ - "Call the `getDefinitionsProductType` operation … using the `PRODUCT` product type and `LISTING_OFFER_ONLY` as the value for the `requirements` parameter."
60
+ - "Amazon product types are hierarchal, with the `PRODUCT` product type as the root for all product types. Sales terms are defined on the root `PRODUCT` product type, which should be used when listing items with sales terms only."
61
+ - "Prepare the listing submission with attributes adhering to the JSON Schema for the `PRODUCT` product type using the ASIN or product identifier for the item found when searching the Amazon catalog."
62
+ - "Note that offer-only listings are not supported for vendors at this time."
63
+ - The model's `requirements` enum describes `LISTING_OFFER_ONLY` as "Indicates the submitted data contains sales terms only."
64
+ - Amazon's example body for an offer-only put names the ASIN in `merchant_suggested_asin`, with `condition_type` and the offer attributes (`fulfillment_availability` or `purchasable_offer`).
65
+
66
+ [official] (Building Listings Management Workflows Guide, as above; listingsItems_2021-08-01.json at the pin, `ListingsItemPutRequest`; Submit Listings data, https://developer-docs.amazon/sp-api/docs/submit-listings-data.md, updatedAt 2026-10-23, read 2026-10-27)
67
+
68
+ 5. **RULE: the new-item path.** For an item Amazon does not have, the guide's steps after the catalog search are: `searchDefinitionsProductTypes` for the product type; `getDefinitionsProductType` for its schema; prepare the attributes; "Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities … You must ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met"; `putListingsItem`; read `ACCEPTED` or `INVALID`; then the notifications or `getListingsItem` with `includedData=issues`.
69
+ - On `requirements`: "To list an item with both product facts and sales terms, use the `LISTING` as the value for the `requirements` parameter to retrieve a JSON Schema with both product and offer attributes. To list an item with product facts only, use the `LISTING_PRODUCT_ONLY` … This enables you to create items that are purchasable or procurable in one submission or to create inactive items with sales terms provided later."
70
+
71
+ [official] (Building Listings Management Workflows Guide, as above)
72
+
73
+ 6. **RULE: product types not yet in the API.** "For product types not yet launched for these APIs, you can create new offer-only listings items, edit sales terms for listings items, or delete listings items. However, you cannot create new listings items with product facts until the appropriate product type is launched in these APIs." The Listings Items API page adds that for such product types "offer-only submissions for existing ASINs and partial updates are supported by using the `PRODUCT` product type" (as read in `research/method/listing-writes.md`, item 11).
74
+ [official] (Building Listings Management Workflows Guide, as above)
75
+
76
+ 7. **RULE: a put on an existing SKU replaces it.** "The `putListingsItem` operation creates a new listing or replaces the existing content of a listing. Existing attributes may be dropped if omitted from the `putListingsItem` submission. For example, if the listing previously contained bullet points and a `putListingsItem` submission is made with the `LISTING_OFFER_ONLY` requirements without including the bullet points, the `putListingsItem` submission will remove the bullet points content on existing listings."
77
+ - The troubleshooting page, under `4005013`: "The information provided matches an item that is already in your catalog (SKU: `matched_sku`; ASIN: `matched_asin`). Items cannot be duplicated in your catalog." Its explanation: "A SKU is an un-editable attribute; after the item is created, it cannot be changed." Its advice: "Build a workflow to surface any pre-existing catalog data for the SKU using the `getListingsItem` and `getCatalogItem` APIs."
78
+
79
+ [official] (Create or fully update a listing, https://developer-docs.amazon/sp-api/docs/create-a-listing.md, updatedAt 2026-09-09, read 2026-10-27; Listings Items API Issues Troubleshooting, https://developer-docs.amazon/sp-api/docs/listings-items-api-issues-troubleshooting.md, updatedAt 2026-09-09, read 2026-10-27)
80
+
81
+ 8. **RULE: restrictions are read by ASIN.** `getListingsRestrictions` requires `asin`, `sellerId` and `marketplaceIds`; `conditionType`, `reasonLocale` and `productType` are optional. Its reason codes are `APPROVAL_REQUIRED` ("A path forward link will be provided"), `ASIN_NOT_FOUND` ("The specified ASIN does not exist in the requested marketplace") and `NOT_ELIGIBLE` ("No path forward link will be provided"). The tutorial: "If there are no restrictions for the specified `conditionType` (when provided) in the specified Amazon store, the list of restrictions in the response will be empty", and "Each Amazon store ID included in the `marketplaceIds` parameter counts as a separate request against the rate limit." The API page: "If no restrictions exist, you can then call the Listings Items API to create offer-only listings."
82
+ - The model describes `productType` as: "The product type of the item. When provided with the brand name, the API evaluates GTIN exemption restrictions in addition to brand restrictions for the specified product type." The operation has no brand parameter at the pin or on `main` (both read 2026-10-27). How the brand name is provided is not stated (open question 2).
83
+ - For a product with no ASIN, no restrictions read exists before creation; `research/method/listing-writes.md` and `research/elements/attributes-and-browse-nodes.md` record that gating on a listing shows as `QUALIFICATION_REQUIRED` issues (P-attributes-and-browse-nodes-23). The model's issue categories include "`QUALIFICATION_REQUIRED`: Approval or qualification is required to list the product."
84
+
85
+ [official] (listingsRestrictions_2021-08-01.json at the pin; Listings Restrictions API, https://developer-docs.amazon/sp-api/docs/listings-restrictions-api.md, updatedAt 2026-09-29; Get listings restrictions for an item in the catalog, https://developer-docs.amazon/sp-api/docs/get-listings-restrictions.md, updatedAt 2026-09-30; listingsItems_2021-08-01.json at the pin, `Issue.categories`; all read 2026-10-27)
86
+
87
+ ### C. The product type and its schema
88
+
89
+ 9. **RULE: finding the product type.** `searchDefinitionsProductTypes` takes `keywords` ("**Note:** Cannot be used with `itemName`"), `itemName` ("Title of ASIN to get product type recommendation"), `marketplaceIds` (required), `locale` ("Locale for display names in response") and `searchLocale` ("Language used for `keywords` or `itemName` parameters. Defaults to primary locale of the marketplace"). Each returned product type has `name`, `displayName` and `marketplaceIds`. Its default rate is 5, burst 10.
90
+ - The FAQ: "If you have a product title, you can get a high-confidence recommendation for the product type by passing the `itemName` parameter. With the `itemName` parameter, you can combine the product title and description to get more granular product type suggestions. You can also use `keywords` to search through product types or pass an empty parameter to return the entire list of available product types."
91
+ - The guide: "You don't need to call `searchDefinitionsProductTypes` operation for every new seller or vendor item. Instead, cache the response … and suscribe to `PRODUCT_TYPE_DEFINITIONS_CHANGE`". (Amazon's spelling.)
92
+ - The guide's recommendation wording is "a high-confidence recommendation for the correct product title by passing `itemName`"; the FAQ's is "for the product type". The FAQ's reading is the one the operation's model supports ("Title of ASIN to get product type recommendation").
93
+
94
+ [official] (definitionsProductTypes_2020-09-01.json at the pin, `searchDefinitionsProductTypes`; Listings APIs FAQ, as above; Building Listings Management Workflows Guide, as above)
95
+
96
+ 10. **RULE: the schema's parameters for a creation.** `getDefinitionsProductType` takes `productType`; `marketplaceIds` (one); `requirements` (`LISTING`, `LISTING_PRODUCT_ONLY`, `LISTING_OFFER_ONLY`); `requirementsEnforced` (`ENFORCED` default, `NOT_ENFORCED` for partial payloads); `locale` ("Locale for retrieving display labels and other presentation details. Defaults to the default language of the first marketplace in the request"); `productTypeVersion` (`LATEST` default); `parentageLevel` (`NONE`, `CHILD`, `PARENT`); and `sellerId` ("When provided, seller-specific requirements and values are populated within the product type definition schema, such as brand names associated with the selling partner"). Its default rate is 5, burst 10.
97
+ - `parentageLevel`: "When provided, the schema is simplified by resolving all conditional logic related to the specified parentage level". The Retrieve page's table: `CHILD` "The `parent_sku` attribute is required"; `PARENT` "Includes attributes applicable to variation group containers"; `NONE` "Variation-related attributes are excluded." "When `parentageLevel` is omitted, the full schema with all conditional logic is returned."
98
+ - The Retrieve page on `sellerId`: "Include the optional `sellerId` parameter to retrieve the seller-specific attributes, including B2B audience values … If the `sellerId` is not provided, the API returns a generic schema without the seller-specific configurations."
99
+ - The schema itself is a link: "The links provided are valid for seven days." The response carries `productTypeVersion` (`version`, `latest`, `releaseCandidate`), `propertyGroups`, and a `checksum` on `schema` and `metaSchema` (`research/method/listing-writes.md`, items 3–5, P-listing-writes-1, P-listing-writes-15).
100
+
101
+ [official] (definitionsProductTypes_2020-09-01.json at the pin, `getDefinitionsProductType`; Retrieve a Product Type Definition, https://developer-docs.amazon/sp-api/docs/retrieve-a-product-type-definition.md, updatedAt 2026-09-09, read 2026-10-27)
102
+
103
+ 11. **RULE: which schema keywords decide what a value must look like.** The meta-schema extends JSON Schema Draft 2019-09 with a custom vocabulary: "If you choose to ignore this custom vocabulary and use only the standard JSON Schema Draft 2019-09 vocabularies, you may get validation errors." Its keywords:
104
+ - `editable`: "Indicates whether or not a property value can be modified for an existing item. Properties that can't be modified may still be required for a valid submission."
105
+ - `enumNames`: "Contains an array of display labels for a corresponding array of `enum` values." The value written is the `enum` value, not its label (as `research/method/listing-writes.md` and P-inventory-and-fulfillment-15 already hold for shipping templates).
106
+ - `maxUtf8ByteLength` / `minUtf8ByteLength`: "measured in UTF-8 bytes".
107
+ - `selectors`: "Contains an array of property names that define the combination of properties that make an object unique."
108
+ - `maxUniqueItems` / `minUniqueItems`: "Defines the maximum number of unique items in an array. Use in conjunction with `selectors`."
109
+ - `$lifecycle`, `replacedBy`, `replaces`, `enumDeprecated` ("Instances of deprecated `enum` values must be replaced with valid values before the deprecated values are removed").
110
+ - `hidden`: "Determines if a property should be hidden in Amazon user interfaces." It is "Informational".
111
+ - Beyond the vocabulary, the standard keywords the guide names are what make a submission valid: "the required attributes are provided, all values are valid, any conditional rules are accounted for". The guide's variation section names the conditional form: "When `parentageLevel` is not provided, refer to the conditional requirements (`allOf`) within the `ProductTypeDefinition` to identify which properties become mandatory based on the selected variation theme."
112
+
113
+ [official] (Amazon Product Type Definitions Meta-Schema (v1), https://developer-docs.amazon/sp-api/docs/product-type-definition-meta-schema.md, updatedAt 2026-09-09, read 2026-10-27; Building Listings Management Workflows Guide, as above)
114
+
115
+ 12. **RULE: the schema's property groups.** Amazon's LUGGAGE example response groups its properties as `offer`, `images`, `shipping`, `variations`, `safety_and_compliance`, `product_identity` and `product_details`. `product_identity` is described as "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)" and lists `item_name`, `brand`, `supplier_declared_has_product_identifier_exemption`, `externally_assigned_product_identifier`, `merchant_suggested_asin`, `item_type_keyword`, `item_type_name`, `model_number` and `manufacturer`. `safety_and_compliance` is "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))". The group lists are one product type's in one store; the run-time schema holds the set for the seller's product type and store.
116
+ [official] (Manage Product Listings with the Selling Partner API, https://developer-docs.amazon/sp-api/docs/manage-product-listings-guide.md, updatedAt 2026-09-09, read 2026-10-27)
117
+
118
+ 13. **RULE: the schema changes.** The FAQ: "Amazon reviews product attributes regularly and plans necessary updates for the last week of every month … Before you update any attribute for your listing submission, use the Product Type Definitions API to get the latest JSON schema." A schema change shows in `checksum`, in `PRODUCT_TYPE_DEFINITIONS_CHANGE`, and in the monthly announcements. (`research/method/listing-writes.md`, item 5; P-listing-writes-15.)
119
+ [official] (Listings APIs FAQ, as above)
120
+
121
+ ### D. Product identity
122
+
123
+ 14. **RULE: the identifier attribute and its lengths.** The troubleshooting page lists, under `90225`, "`externally_assigned_product_identifier`: 12 characters expected for UPC, 13 for EANs, 14 for GTINs". Under `90188`, "Value does not satisfy ISBN/UCCID. Checksum requirements": "Each `external_id_type` has an expected number of characters … 12 characters expected for UPC, 13 characters expected for EANs, 14 characters expected for GTINs." The attribute's inner properties (its type and value fields) are the schema's, read at run time.
124
+ [official] (Listings Items API Issues Troubleshooting, as above)
125
+
126
+ 15. **RULE: whose GTIN.** Product detail page rules: "You must only use GTINs that you own or are authorized to use. GTINs must be purchased directly from GS1, or you must have explicit authorization from the GTIN prefix owner. Listing submissions with unauthorized GTINs will be blocked." "You must not use false product identification information in product detail pages." "You must not create a product detail page for a product already in Amazon's catalog." "Unless your listing was created with a GTIN exemption, you cannot edit or update the product ID of an existing listing. The product ID is a non-editable value and cannot be modified once a listing is created, unless it was created with a GTIN exemption."
127
+ - The troubleshooting page's identity issues:
128
+ - `4005007`: "A match for the value of `attribute_name` could not be found for the brand specified." Explanation: "This issue is returned when the item submitted has an external ID that is not registered for use with the provided brand … If correct, you need to provide proof of affiliation between the company the External ID is registered to and the brand you selected (for example, a license agreement)." The listed evidence ends "GS1 Certificate for the UPC/EANs should be attached in the related Item."
129
+ - `4005008`: "The value of `attribute_name` is either restricted or not registered in GS1. Contact Amazon to provide the relevant GS1 certificate."
130
+ - `100980`: "Your barcode is already associated with another product ASIN, which appears to be different from the product you are trying to list." Advice: "Use the Catalog Items API to look up existing ASINs associated with the barcode."
131
+ - `101165`: "Your item with `SKU`, external product ID, and ASIN matches multiple products because these identifiers are not unique."
132
+ - `101166`: "Amazon requires a one-to-one mapping between SKUs and external product IDs. Each unique ASIN and external ID combination must have its own distinct SKU."
133
+ - Several of these rows send the reader to Vendor Central or a vendor manager; the page does not give the seller route for each.
134
+
135
+ [official] (Product detail page rules, G200390640 v21, capture `G200390640-v21`, https://sellercentral.amazon.com/help/hub/reference/external/G200390640, read 2026-10-14; Listings Items API Issues Troubleshooting, as above)
136
+
137
+ 16. **RULE: the GTIN exemption.** The FAQ: "Is it possible to create a product on Amazon without an ASIN or product identifier (UPC, GTIN, or EAN) with the Listings Items API v2021-08-01?" "Yes. If you don't have a product identifier, you can create a product with a GTIN exemption. For exemption, you must submit a manual exemption request through your Seller Central account. … After you have received an approval, you can create a listings submission through the Listings Items API v2021-08-01. You must provide the brand name approved for the GTIN exemption and set the `supplier_declared_has_product_identifier_exemption` attribute to `true`."
138
+ - The Seller Central page the FAQ links, Product IDs (GTIN) exemption (G200426310), has no capture and was not read (see the source note above).
139
+ - An Amazon-named Seller Forums post ("Rose_Amazon", shown "2 years ago"; the fetched text shows no staff badge) adds: "wait 30 minutes before adding your product in the same way you would while listing with a GTIN"; "enter the Category and Brand/Publisher name exactly as they appear in your exemption approval notice"; "If you use a different case or insert additional characters or spaces, the system will not recognize your exemption."; "category-level approvals may be required in addition to GTIN exemption approvals"; "You will have to apply for the GTIN exemption each time you want to list under a different brand or category."
140
+
141
+ [official] (Listings APIs FAQ, as above; Seller Forums, "Listing Lounge: Your GTIN Exemption Was Approved, But Now You Received An Error Message. What's Next?", https://sellercentral.amazon.com/seller-forums/discussions/t/a1257c84-e37a-439d-9c04-d731a0783edc, read 2026-10-27)
142
+
143
+ 17. **RULE: the brand and Brand Registry.** sell.amazon.com's listing guide (Apr 29, 2026): "your ability to create a new product detail page may depend on your relationship with the product: If the product is part of a brand enrolled in Amazon Brand Registry, you need to be a Brand Representative or Reseller authorized by the brand to list it using our standard processes. If the product belongs to certain categories, you may be prompted during the listing process to obtain approval from Amazon." And: "After enrolling your brand in Amazon Brand Registry, only you and other sellers associated with your brand can create or suggest updates to your product detail pages using our standard listing processes."
144
+ - The schema's `sellerId` read populates "brand names associated with the selling partner" (item 10).
145
+ - Product detail page rules: "Create a new ASIN when selling a product under a different trademark (brand or manufacturer name) rather than editing an existing ASIN."
146
+ - The Amazon-named forum post (item 16) names two brand errors: 5665, "the brand attribute on a listing does not match the name of the brand that produced the product", and 5461, "you have not been authorized to create new ASINs for the brand", resolved through Seller Support with evidence of authenticity. These are Seller Central error codes; whether the Listings Items API returns the same codes was not seen on a developer page.
147
+ - Brand roles and precedence are in `research/angles/brand-protection-and-catalog-contribution.md` (P-brand-protection-and-catalog-contribution-2) and the FAQ: "Brand owners have the highest precedence to update data on the product details page on Amazon."
148
+
149
+ [official] (How to create Amazon product listings, https://sell.amazon.com/blog/amazon-product-listings, dated Apr 29, 2026, read 2026-10-27; Product detail page rules, G200390640 v21, as above; Seller Forums post, as above; Listings APIs FAQ, as above)
150
+
151
+ ### E. The request
152
+
153
+ 18. **RULE: the put request.** `PUT /listings/2021-08-01/items/{sellerId}/{sku}`. Path: `sellerId` ("A selling partner identifier, such as a merchant account or vendor code") and `sku` ("A selling partner-provided identifier for an Amazon listing"). Query: `marketplaceIds` (required), `includedData` (`identifiers`, `issues`; "Default: `issues`"), `mode` (`VALIDATION_PREVIEW`), `issueLocale`. Body: `productType` and `attributes` (required) and `requirements` (`LISTING`, `LISTING_PRODUCT_ONLY`, `LISTING_OFFER_ONLY`). The model's default rate is 5, burst 10; the rate-limit page gives 5 per account-application pair, 100 per application, burst 5, with relationship updates at 100 a second per application.
154
+ - Amazon's create example: `PUT …/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123?marketplaceIds=ATVPDKIKX0DER&issueLocale=en_US` with `{"productType": "LUGGAGE", "requirements": "LISTING", "attributes": {"condition_type": […], "merchant_suggested_asin": […], "item_name": [{"value": …, "language_tag": "en_US", "marketplace_id": …}], "brand": […], "color": […], "main_product_image_locator": [{"media_location": …, "marketplace_id": …}], …}}`.
155
+ - That example names `merchant_suggested_asin` on a full `LISTING` put. The guide's new-item path names no ASIN, and the FAQ's GTIN answer names a product identifier or the exemption. The example is read as a listing against a known ASIN, not as the new-item shape (the same reading `research/method/listing-writes.md`, item 13, gives a mislabelled example: the model and the workflow decide).
156
+ - The seller id in the path is read from an Amazon reply, never asked (P-sp-api-access-3; the door's `references/door.md`).
157
+
158
+ [official] (listingsItems_2021-08-01.json at the pin, `putListingsItem`, `ListingsItemPutRequest`; Submit Listings data, as above; Listings Items API Rate Limits, https://developer-docs.amazon/sp-api/docs/listings-items-api-rate-limits.md, updatedAt 2026-09-09, read 2026-10-27)
159
+
160
+ 19. **RULE: text values carry the store's language.** Amazon's examples write text with `language_tag` and `marketplace_id` (`research/method/listing-writes.md`, item 7; P-listing-writes-4, P-marketplaces-and-languages-7). The participation row gives the store's `defaultLanguageCode` (item 1). `getDefinitionsProductType`'s `locale` sets "display labels and other presentation details", so it is not the language of the values written; the allowed tags are in the store's schema (`$defs.language_tag`, P-marketplaces-and-languages-7). Listing Creation for Global Accounts (G201468480 v3) puts listings in each store's language (as read in `research/method/listing-writes.md`, P-listing-writes-22).
161
+ [official] (definitionsProductTypes_2020-09-01.json at the pin; sellers.json at the pin)
162
+
163
+ 20. **RULE: price and currency.** "The `purchasable_offer` attribute defines the complete pricing and offer configuration for a product listing on Amazon. It is structured as an array of offer objects, with each offer uniquely identified by `marketplace_id`, `currency`, and `audience`." `our_price` is the "Base selling price", written as `[{"schedule": [{"value_with_tax": 7.0}]}]`. "The API derives selectors from the Amazon store in the request. For better control, include the selector properties (`currency`, `marketplace_id`, and `audience`) within the payload". Amazon's offer-only example writes `"audience": "ALL", "currency": "USD"` for `ATVPDKIKX0DER`. The store's currency is the participation row's `defaultCurrencyCode` (item 1).
164
+ - A preview "returns the pricing validation issues when you include the price attributes in the request body" (Preview errors before creating or fully updating a listing).
165
+
166
+ [official] (Manage purchasable offer, https://developer-docs.amazon/sp-api/docs/manage-purchasable-offer.md, updatedAt 2026-09-09; Submit Listings data, as above; Preview errors before creating or fully updating a listing, https://developer-docs.amazon/sp-api/docs/preview-errors-before-creating-a-listing.md, updatedAt 2026-09-09; all read 2026-10-27)
167
+
168
+ 21. **RULE: fulfilment: merchant-fulfilled against FBA.** "The `fulfillment_availability` attribute is an array that accepts one or more distinct fulfillment records, each keyed by the `fulfillment_channel_code` to which the fulfillment record is applicable." The MFN example is `{"fulfillment_channel_code":"DEFAULT","quantity":10,"restock_date":"2025-01-01","lead_time_to_ship_max_days":5}`.
169
+ - "The available `fulfillment_channel_code` values differ by selling partner and Amazon store, based on the programs that a selling partner is enrolled in. … Include the `sellerId` parameter to retrieve JSON schemas that contain the selling partner-specific `fulfillment_channel_code` values and the fulfillment information that is supported for each `fulfillment_channel_code` value. For example, `quantity` information is supported for MFN fulfillment, but not for Fulfillment by Amazon (FBA) fulfillment."
170
+ - The page's table: `DEFAULT` MFN, "Provide quantity for standard fulfillment by a selling partner"; `AMAZON_NA`, `AMAZON_EU`, `AMAZON_JP`, "Enable FBA fulfillment in the … region". Its MFN-plus-FBA example adds `{"fulfillment_channel_code":"AMAZON_NA"}` with no quantity, and "When FBA inventory is available, it is used first. MFN inventory is used after the FBA inventory is depleted."
171
+ - Shipping templates: "Shipping settings for listings items are configured on the account-level by default for sellers in Seller Central. … By providing the `sellerId` parameter with the Product Type Definitions API, you can retrieve the available shipping templates configured by the seller as an enumeration on the merchant_shipping_group attribute value."
172
+ - What an FBA offer needs beyond the channel code: dangerous-goods (hazmat) and battery information "When creating or converting a listing for FBA" (`research/elements/attributes-and-browse-nodes.md`, item 42; P-attributes-and-browse-nodes-16), and units sent in to Amazon, which is the inbound path, not the listing.
173
+
174
+ [official] (Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases, https://developer-docs.amazon/sp-api/docs/manage-amazon-haul-advanced-multiple-offer-multiple-fulfillment-use-cases.md, updatedAt 2026-09-09; Submit Listings data, as above; both read 2026-10-27)
175
+
176
+ 22. **RULE: images are given as locations Amazon fetches.** "The Listings Items API accepts product images and other media content attributes from the following sources: Publicly accessible Amazon S3 bucket content downloaded through HTTP or HTTPS URL; Publicly accessible Amazon CloudFront distribution content …; Private Amazon S3 bucket content downloaded through S3 URL …; Images hosted on third-party servers that are publicly available to Amazon." "Private Amazon S3 content is treated as immutable … New media content requires a new Amazon S3 object key." The variants are `MAIN` (`main_product_image_locator`), `PT01`–`PT08` (`other_product_image_locator_{1-8}`) and `SWCH` (`swatch_product_image_locator`); "Supported image variants and their requirements differ by product type and marketplace. To determine which image attributes are available for your product type, call the `getDefinitionsProductType` operation." "You can include all image attributes in a single `putListingsItem` request".
177
+ - Amazon's pages give the image count differently (the workflows guide: "A main product image and up to nine secondary images"); `research/method/listing-writes.md`, item 8, records the disagreement, and the schema binds (P-images-and-video-17).
178
+ - Images map to the ASIN in every store where it exists (P-listing-writes-10).
179
+ - On processing time, Amazon's pages say: "If your image is selected for display, it can take up to 24 hours after you upload it to appear on the product detail page" (G1881 v28) and "It can take up to 24 hours after you add an image for it to appear on the website" (G200216080 v15). No developer page read states a processing time for an API image submission.
180
+
181
+ [official] (Submit media attributes, https://developer-docs.amazon/sp-api/docs/submit-media.md, updatedAt 2026-10-20, read 2026-10-27; Building Listings Management Workflows Guide, as above; Product image guide, G1881 v28, capture `G1881-v28`; Add product images and video, G200216080 v15, capture `G200216080-v15`; both read 2026-10-14)
182
+
183
+ 23. **RULE: compliance attributes are the store schema's.** The GPSR attributes (`gpsr_manufacturer_reference`, `dsa_responsible_party_address`, `gpsr_safety_attestation`, `compliance_media`) are named for EU stores, and "You must submit the required GPSR information when you create your listing … for each store" (`research/angles/marketplaces-and-languages.md`, G3; P-marketplaces-and-languages-11). Battery, dangerous-goods, safety-data-sheet, Prop 65 and CPSIA values are the seller's declaration (P-attributes-and-browse-nodes-16). sell.amazon.com's guide on the Safety and Compliance tab: "If it's a safety hazard for children under a certain age, has safety certifications, needs batteries or has other required components, it's important to note that here."
184
+ - WEEE and packaging or battery Extended Producer Responsibility: no developer page read names a listing attribute for them. The release notes name EPR reports ("EPR Monthly Report, EPR Quarterly Report, and EPR Annual Reports"), which are reports, not listing attributes. Where a store's schema names a compliance attribute as required, the schema's `required` is the rule; this file holds no list of which store requires what.
185
+
186
+ [official] (as cited in the two files named; How to create Amazon product listings, as above; SP-API Release Notes, https://developer-docs.amazon/sp-api/docs/sp-api-release-notes.md, updatedAt 2026-10-26, read 2026-10-27)
187
+
188
+ ### F. Variations
189
+
190
+ 24. **RULE: parent first, then children.** "With the Listings Items API and `JSON_LISTINGS_FEED`, a parent listings item is created first and each child listings item refers to the parent listings item with the child_parent_sku_relationship attribute." The guide:
191
+ - Parent: schema with `parentageLevel=PARENT`; "A parent listings item must have the following attributes: `parentage_level`: `value` property set to `parent`; `child_parent_sku_relationship`: `child_relationship_type` property set to `variation`; `variation_theme`: `name` property set to a value applicable for your product". "The parent listing is a non-buyable entity used to relate child products. A parent listing must not be a buyable product."
192
+ - Children: schema with `parentageLevel=CHILD`; "Most product facts must be replicated across all listings within the variation family." Each child has `parentage_level` `child`, `child_parent_sku_relationship` with `child_relationship_type` `variation` and `parent_sku` "set to the SKU identifier of the parent listings item", and `variation_theme` "set to the same value as the parent listing item".
193
+ - "When you select a variation theme for a child listing item, you must provide the corresponding properties. … When using `parentageLevel=CHILD`, these mandatory properties appear directly in the schema as required attributes."
194
+ - "new listings must avoid using deprecated enumeration values" (`enumDeprecated` in `$lifecycle` within `variation_theme`).
195
+ - Standalone listings: "include `parentageLevel=NONE` … Variation-related attributes are excluded from the returned schema."
196
+ - Reading the family back: `getCatalogItem` or `searchCatalogItems` with `includedData=relationships`, or `searchListingsItems` with `variationParentSku`.
197
+ - Relationship writes have their own rate: "Ensure updates containing relationship updating attributes (`child_parent_sku_relationship`, `package_contains_sku`) do not exceed the application's rate limit for relationship updates."
198
+ - The family rules (non-varying attributes, same function, review sharing) are in `research/elements/variations.md` (P-variations-2, P-variations-4, P-variations-14).
199
+
200
+ [official] (Submit Listings data, as above; Building Listings Management Workflows Guide, as above; Listings Items API Rate Limits, as above)
201
+
202
+ ### G. The preview
203
+
204
+ 25. **RULE: a preview of a creation.** "To preview the results after you create or fully update a listing, call the `putListingsItem` operation with the `mode` query parameter set to `VALIDATION_PREVIEW`." "`VALIDATION_PREVIEW` mode synchronously performs the same checks that are done on production submissions, but without persisting to your catalog." The guide: "Validation preview provides an environment to test listing workflows and identify validation errors before submission that prevent listing creation." The model's `VALID`: "The listings submission was valid. Only returned when the `mode` is `VALIDATION_PREVIEW`." Manage Listings Issues: "This mode has lower rate limits and is intended for testing a small number of listings. It is not designed for production workflows." The rate-limit page states the preview limit, "Validation previews: Limit of 20 requests per application per second", in the `patchListingsItem` row; the `putListingsItem` row names no preview limit. (`research/method/listing-writes.md`, items 15–17; P-listing-writes-5.)
205
+ [official] (Preview errors before creating or fully updating a listing, as above; Listings APIs FAQ, as above; Building Listings Management Workflows Guide, as above; listingsItems_2021-08-01.json at the pin; Listings Items API Rate Limits, as above)
206
+
207
+ 26. **RULE: a required attribute the data does not fill.** The troubleshooting page: "`90220`: `attribute_name` is required but not supplied." "This issue occurs when a required attribute was not provided. Example: `item_package_dimensions` is required but not supplied. Provide information for the required attribute as indicated in the issue message." The model's issue has `attributeNames` ("Names of the attributes that are associated with the issue, if applicable") and categories including "`MISSING_ATTRIBUTE`: One or more required attributes are missing." The model's static case for a put preview of SKU `VALIDATION_INVALID` answers `"status":"INVALID"` with `{"code":"90220","message":"'condition_type' is required but not supplied.","severity":"ERROR","attributeNames":["condition_type"],"categories":["MISSING_ATTRIBUTE","LISTING"]}` (a canned reply, item 31, so it shows the shape only).
208
+ [official] (Listings Items API Issues Troubleshooting, as above; listingsItems_2021-08-01.json at the pin, `Issue`, `putListingsItem` 200 `x-amzn-api-sandbox`)
209
+
210
+ 27. **RULE: the preview names the ASIN it matches.** `includedData=identifiers` returns `identifiers`: "Identity attributes associated with the item in the Amazon catalog, such as the ASIN", per store (`marketplaceId`, `asin`). The model's static `VALIDATION_VALID` case returns an ASIN in `identifiers`; its `VALIDATION_INVALID` case returns `[]`. Whether a real preview of a new item with no catalog match returns an empty `identifiers` was not seen on any page (open question 4).
211
+ [official] (listingsItems_2021-08-01.json at the pin, `ItemIdentifiers`, `ItemIdentifiersByMarketplace`)
212
+
213
+ ### H. The write and what it answers
214
+
215
+ 28. **RULE: `ACCEPTED` and `INVALID` on a creation.** "Inspect the response to identify if the submission status was `ACCEPTED` or `INVALID`. If accepted, initial validations have passed and the data has been submitted for further processing with the Amazon catalog. If invalid, one or more validation issues prevented acceptance … Correct the validation issues and resubmit." The response requires `sku`, `status` and `submissionId` ("The unique identifier of the listings item submission"). (P-listing-writes-6.)
216
+ [official] (Building Listings Management Workflows Guide, as above; listingsItems_2021-08-01.json at the pin, `ListingsItemSubmissionResponse`)
217
+
218
+ 29. **RULE: asynchronous issues and the read-back.** The FAQ: "If you upload the listings data with the Listings Items API v2021-08-01 and the submission status is `ACCEPTED`, then the submission passed the synchronous validations. Amazon sends the submission downstream to create or update the SKU. There are a number of downstream processes that are then performed to create or update an item in the Amazon catalog. Any of these downstream processes can generate issues which are returned asynchronously. For example, if a listing submission contains data which conflicts with another item in the Amazon catalog."
219
+ - "I submitted my listing without issues, but I cannot find it listed. Where is it?" "Your listing might have experienced an issue after submission (an asynchronous issue). To view such issues, use the `getListingsItem` operation."
220
+ - "Why is there no summary information in my Listings Item Get API response?" "The summary view displays information about the ASIN you are creating a listing against. If the summary view is not populated it is because the submission failed and did not match an ASIN."
221
+ - "How can I confirm the creation of my product in the Amazon catalog?" Amazon sends `LISTINGS_ITEM_STATUS_CHANGE` "when the buyability changes for a listing item, or upon the creation or deletion of a listing item … For example, if `DISCOVERABLE` is not present, Amazon retail cannot search for the listings item."
222
+ - The status enum: `BUYABLE`, "The listings item can be purchased by shoppers. This status does not apply to vendor listings"; `DISCOVERABLE`, "The listings item is visible to shoppers." A summary carries `marketplaceId`, `asin`, `productType`, `status`, `createdDate` and `lastUpdatedDate`.
223
+ - `getListingsItem` takes `includedData` of `summaries`, `attributes`, `issues`, `offers`, `fulfillmentAvailability`, `procurement`, `relationships` and `productTypes`.
224
+ - The FAQ's timing: `getListingsItem` "directly queries the current state, which is why the results are available faster (within 1-5 minutes)"; the notifications run 15–20 minutes behind. The door subscribes to no notifications (P-triggers-12, as recorded in `research/README.md`, T6), so every read-back is a pull.
225
+ - The September 30, 2026 release notes: "Added PRODUCT-level and LISTING-level issue classification to the `categories` attribute in issue descriptions returned by the `getListingsItem` and `searchListingsItems`. You can use this to identify whether an issue originates from the ASIN (product level) or the SKU (listing level)."
226
+ - No page read states how long Amazon takes to assign an ASIN to a new item.
227
+
228
+ [official] (Listings APIs FAQ, as above; listingsItems_2021-08-01.json at the pin, `ItemSummaryByMarketplace`, `getListingsItem`; SP-API Release Notes, September 30, 2026 entry, as above)
229
+
230
+ 30. **RULE: a seller's report of an asynchronous refusal.** In GitHub issue #2711 ("Cannot create new listings and ASINs", opened 2023-09-22), a developer's `putListingsItem` creations were accepted and `getListingsItem` then carried `8566`, "SKU does not match any ASIN and the product data provided is not eligible for ASIN creation", and `8572`, "You are using UPCs, EANs, ISBNs, ASINs, or JAN codes that do not match the products you are trying to list". Amazon's Solutions Architect answered only by pointing to the developer's support case. The listings used the brand "Generic".
231
+ [opinion] (the developer's report), with an [official] reply that gives no rule (https://github.com/amzn/selling-partner-api-models/issues/2711, read 2026-10-27)
232
+
233
+ ### I. The sandbox
234
+
235
+ 31. **RULE: what the static sandbox answers on the create path.** "The SP-API static sandbox uses pattern matching to return static, mock responses." The sandbox support table lists the Listings Items API and the Listings Restrictions API as "Static" and "AI" (the local sample AI sandbox). At the pin:
236
+ - `putListingsItem` answers an empty-body pattern with `ACCEPTED`, a fixed `submissionId` and no issues; SKU `VALIDATION_VALID` with `mode=VALIDATION_PREVIEW` and `includedData=identifiers,issues` with `VALID` and a fixed ASIN; SKU `VALIDATION_INVALID` with `INVALID` and the `90220` and `90000900` issues of item 26; SKU `BadSKU` with 400.
237
+ - `searchDefinitionsProductTypes` answers one product type, `LUGGAGE`.
238
+ - `getDefinitionsProductType` answers a definition whose `schema.link.resource` is `https://schema-url` and `metaSchema.link.resource` `https://meta-schema-url`, placeholders that are not a schema.
239
+ - Amazon's own sample AI sandbox sends every put to production with `mode=VALIDATION_PREVIEW` "Rather than reimplement Amazon's validation" (`research/method/listing-writes.md`, item 19).
240
+ - So a sandbox answer shows the request's path, signing, route and body shape, and nothing about the seller's product type, its schema, the identity checks, the preview's verdict or a real submission (P-listing-writes-11).
241
+
242
+ [official] (Selling Partner API Sandbox, https://developer-docs.amazon/sp-api/docs/sp-api-sandbox.md, updatedAt 2026-09-09, read 2026-10-27; listingsItems_2021-08-01.json and definitionsProductTypes_2020-09-01.json at the pin, `x-amzn-api-sandbox`)
243
+
244
+ ### J. Build International Listings
245
+
246
+ 32. **RULE: Build International Listings is a Seller Central tool.** "The Build International Listings tool helps you create and update offers from a single source store to one or more target stores." It "Creates offers from a source store to a target store where the same ASINs already exist in both stores", "Synchronizes the offer prices in target stores", and "Attempts to translate and create product detail pages in a target store." It does not "Guarantee the creation of new product detail pages", and does not "Check that your products comply with applicable laws and regulations across all stores." "An ASIN must have an active offer in the source store." "If a product detail page with the same ASIN does not exist in the source and target stores, Amazon will attempt to translate and create the product detail page in the target stores. Amazon does not guarantee the creation of a product detail page." The page's steps run through the Build International Listings tool in Seller Central; no developer page read names an operation for it (`research/method/listing-writes.md`, run-time list; P-listing-writes-23).
247
+ [official] (Build International Listings, G202121570 v14, capture `G202121570-v14`, https://sellercentral.amazon.com/help/hub/reference/external/G202121570, read 2026-10-14)
248
+
249
+ ### K. A creation in the change log
250
+
251
+ 33. **RULE: what Amazon keeps of a creation.** The submission answers `submissionId`, `status` and `issues` (item 28); the listing answers `summaries.createdDate` (item 29). No page read describes an operation that returns a listing's history (P-listing-writes-8). A creation therefore has no "before" from Amazon; what was sent and what came back are only what cx keeps.
252
+ [official] (listingsItems_2021-08-01.json at the pin)
253
+
254
+ ### L. Conflict issues and the resolution each names
255
+
256
+ 34. **RULE: each conflict issue names its own way out.** The troubleshooting page, per code:
257
+ - `4005011`: "The value of `attribute_name` conflicts with another item in the Amazon catalogue, `conflicting_asin`. Either change the value to `conflicting_value` or contact Amazon to resolve the conflicting data issue." Explanation: "You might need to change the data being submitted to resolve the conflict with the existing data. If you wish to change any existing values, you need to submit an Amazon Vendor Central Support case."
258
+ - `4005033`: "The value for `attribute_name` cannot be edited. Revert the value to `original_value` and resubmit." Explanation: "If the original value is incorrect and you wish to have the value updated, then submit a Contact Us case", and "There can also be edge cases where the original value is no longer accepted upon resubmission. If this is the case, you should also submit a Contact Us case."
259
+ - `101165`: "Your item with `SKU`, external product ID, and ASIN matches multiple products because these identifiers are not unique. Update these values so they do not conflict with your existing catalog items, then resubmit." Advice: "If identifiers are shared across products, assign unique SKUs and external IDs to each distinct product. If the conflict exists in the catalog, contact Amazon Vendor Central Support to resolve the duplicate entries."
260
+ - The page's support routes are written for vendors (Vendor Central Support) or as "Contact Us"; the seller route is not named per code.
261
+
262
+ [official] (Listings Items API Issues Troubleshooting, https://developer-docs.amazon/sp-api/docs/listings-items-api-issues-troubleshooting.md, updatedAt 2026-09-09, read 2026-10-27)
263
+
264
+ ## What practitioners add
265
+
266
+ - **GTIN exemption through third-party tools.** LitCommerce's help page on product identifiers and GTIN exemption says listings published through its tool cannot create new ASINs, citing "Amazon API limitations for third-party applications" (as summarised by the search result; the page itself was not opened). No Amazon page read says the Listings Items API refuses new-ASIN creation to a third-party application; Amazon's FAQ (item 16) describes the exemption route through the API. [opinion] (LitCommerce, https://help.litcommerce.com/marketplace-integration/supported-platforms/amazon/how-to-sell-on-amazon-with-litcommerce-product-identifiers-and-gtin-exemption, found 2026-10-27, not opened)
267
+ - **Empty summaries after a creation.** A developer in GitHub issue #4276 reports that `summaries` stays empty for a few minutes after a SKU is re-created, until the ASIN and product type fill in (as summarised by the search result; the issue was not opened). It sits beside the FAQ's reading (item 29), which calls an empty summary a submission that failed and did not match an ASIN; the issue carries no position and gives no figure Amazon states. [opinion] (https://github.com/amzn/selling-partner-api-models/issues/4276, found 2026-10-27, not opened)
268
+ - **Exemption approvals that do not take.** Sellers on Seller Forums EU report an approved exemption still asking for a product ID, which the Amazon-named post (item 16) answers with the exact brand and category spelling and the 30-minute wait. [opinion] (Seller Forums EU, "GTIN Exemption approved but still asking for product ID when creating listing", https://sellercentral-europe.amazon.com/seller-forums/discussions/t/1d1ea206-1d48-4cb7-a065-3b9dcb289d09, found 2026-10-27, not opened)
269
+
270
+ ## Published research
271
+
272
+ None was found that bears on the create path. The catalog-reconciliation papers in `research/method/listing-writes.md` (AutoKnow, MAVE) are background for why the Catalog view of a new item can differ from what was submitted.
273
+
274
+ ## Stable enough for a skill
275
+
276
+ - **The order.** The stores; the catalog search by identifier; the offer-only path for an exact match, the new-item path otherwise; the product type; the store's schema; the request; the preview; the write; the read-back. This order is Amazon's own (items 3–5) and does not depend on any figure.
277
+ - **New against existing.** An exact `searchCatalogItems` match by identifier means an offer-only listing on that ASIN; no match means a new item with product facts (item 3).
278
+ - **Per store.** One schema and one put per store, each in its language and currency (items 2, 19, 20).
279
+ - **The schema decides the value.** `required` and its conditionals, `enum` (not `enumNames`), `enumDeprecated`, the length keywords, `selectors`, `maxUniqueItems` and the seller-specific enums decide what a value must look like (items 10, 11, 21).
280
+ - **Identity.** A GTIN the seller owns or is licensed to use, or an approved exemption with the brand exactly as approved (items 15, 16). The product ID cannot be changed after creation except under an exemption (item 15).
281
+ - **The preview.** Persists nothing; answers `VALID` or `INVALID` with issues naming attributes (items 25, 26).
282
+ - **The write.** `ACCEPTED` means the synchronous checks passed and processing began; asynchronous issues follow on `getListingsItem` (items 28, 29).
283
+ - **Done.** `summaries` with an ASIN, `status` holding `BUYABLE` and `DISCOVERABLE`, and no `ERROR` issue, read back, never assumed after a wait (item 29).
284
+ - **Variations.** Parent first, then children, each with the relationship and the parent's theme (item 24).
285
+ - **Sandbox.** Shape and route only (item 31).
286
+
287
+ ## What cx must read at run time
288
+
289
+ - **The stores:** `GET /sellers/v1/marketplaceParticipations` on each connected origin; `marketplace.id`, `defaultLanguageCode`, `defaultCurrencyCode`, `participation.isParticipating`, `participation.hasSuspendedListings`.
290
+ - **The seller id:** from the reply the door names (`references/door.md`; P-sp-api-access-3).
291
+ - **Whether the SKU exists:** `GET /listings/2021-08-01/items/{sellerId}/{sku}` for that store, before a put replaces it (item 7).
292
+ - **Whether Amazon has the item:** `GET /catalog/2022-04-01/items` with `identifiers`, `identifiersType` and `marketplaceIds`, and `includedData=summaries,attributes,identifiers,productTypes,relationships`; `getCatalogItem` per candidate ASIN where several match.
293
+ - **For an existing ASIN:** `GET /listings/2021-08-01/restrictions` with `asin`, `sellerId`, `marketplaceIds` and `conditionType`.
294
+ - **The product type:** `GET /definitions/2020-09-01/productTypes` with `itemName` (or `keywords`), `marketplaceIds` and `searchLocale`.
295
+ - **The schema, per store:** `GET /definitions/2020-09-01/productTypes/{productType}` with one `marketplaceIds`, `requirements`, `sellerId`, `locale` and `parentageLevel`; then the schema document at `schema.link.resource`; keep `productTypeVersion.version` and `schema.checksum`.
296
+ - **The preview:** `PUT /listings/2021-08-01/items/{sellerId}/{sku}?marketplaceIds=…&includedData=identifiers,issues&mode=VALIDATION_PREVIEW&issueLocale=…`.
297
+ - **The write:** the same request without `mode`.
298
+ - **The read-back:** `GET /listings/2021-08-01/items/{sellerId}/{sku}` with `includedData=summaries,attributes,issues,offers,fulfillmentAvailability,relationships`; then `getCatalogItem` on the ASIN the summary names.
299
+ - **Rates:** `x-amzn-RateLimit-Limit` on each reply (P-sp-api-access-11).
300
+
301
+ ## Pages read
302
+
303
+ | Page name | URL | updatedAt or version | Date read | What it gave |
304
+ |---|---|---|---|---|
305
+ | Building Listings Management Workflows Guide | https://developer-docs.amazon/sp-api/docs/building-listings-management-workflows-guide.md | 2026-09-24 | 2026-10-27 | The two create workflows, new against existing, `LISTING` against `LISTING_PRODUCT_ONLY`, `PRODUCT` and `LISTING_OFFER_ONLY`, product types not yet launched, variations, image count, package hierarchies |
306
+ | Create or fully update a listing | https://developer-docs.amazon/sp-api/docs/create-a-listing.md | 2026-09-09 | 2026-10-27 | Put replaces existing content |
307
+ | Preview errors before creating or fully updating a listing | https://developer-docs.amazon/sp-api/docs/preview-errors-before-creating-a-listing.md | 2026-09-09 | 2026-10-27 | Preview on put; pricing issues |
308
+ | Submit Listings data | https://developer-docs.amazon/sp-api/docs/submit-listings-data.md | 2026-10-23 | 2026-10-27 | Create, offer-only, price, inventory, relationship and shipping examples; parent created first |
309
+ | Submit media attributes | https://developer-docs.amazon/sp-api/docs/submit-media.md | 2026-10-20 | 2026-10-27 | Image sources, private S3, variants, all images in one put |
310
+ | Listings APIs FAQ | https://developer-docs.amazon/sp-api/docs/listings-apis-faq.md | 2026-09-09 | 2026-10-27 | Product type steps, GTIN exemption, asynchronous issues, empty summaries, creation notification, 1–5 minutes, single store per feed, precedence |
311
+ | Listings Items API Issues Troubleshooting | https://developer-docs.amazon/sp-api/docs/listings-items-api-issues-troubleshooting.md | 2026-09-09 | 2026-10-27 | 90220, 90225, 90188, 4005013, 4005007, 4005008, 100980, 101165, 101166 |
312
+ | Listings Items API Rate Limits | https://developer-docs.amazon/sp-api/docs/listings-items-api-rate-limits.md | 2026-09-09 | 2026-10-27 | Put rates, relationship rate, preview rate on the patch row only |
313
+ | Listings Restrictions API | https://developer-docs.amazon/sp-api/docs/listings-restrictions-api.md | 2026-09-29 | 2026-10-27 | Restrictions before an offer-only listing; Product Listing role; Static sandbox |
314
+ | Get listings restrictions for an item in the catalog | https://developer-docs.amazon/sp-api/docs/get-listings-restrictions.md | 2026-09-30 | 2026-10-27 | Empty list means no restriction; per-store rate counting |
315
+ | Search available Product Type Definitions; Get Product Type Definition recommendations | https://developer-docs.amazon/sp-api/docs/search-available-product-type-definitions.md; https://developer-docs.amazon/sp-api/docs/get-product-type-definition-recommendations.md | 2026-09-09 | 2026-10-27 | Product Listing role; `itemName` recommendations |
316
+ | Retrieve a Product Type Definition | https://developer-docs.amazon/sp-api/docs/retrieve-a-product-type-definition.md | 2026-09-09 | 2026-10-27 | Seven-day links, `sellerId`, `parentageLevel` table |
317
+ | Amazon Product Type Definitions Meta-Schema (v1) | https://developer-docs.amazon/sp-api/docs/product-type-definition-meta-schema.md | 2026-09-09 | 2026-10-27 | The custom vocabulary |
318
+ | Manage Product Listings with the Selling Partner API | https://developer-docs.amazon/sp-api/docs/manage-product-listings-guide.md | 2026-09-09 | 2026-10-27 | Lifecycle; property groups; `getListingsItem` example |
319
+ | Manage purchasable offer | https://developer-docs.amazon/sp-api/docs/manage-purchasable-offer.md | 2026-09-09 | 2026-10-27 | `purchasable_offer` selectors, `our_price` |
320
+ | Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases | https://developer-docs.amazon/sp-api/docs/manage-amazon-haul-advanced-multiple-offer-multiple-fulfillment-use-cases.md | 2026-09-09 | 2026-10-27 | `fulfillment_availability`, channel codes, MFN and FBA together |
321
+ | Selling Partner API Sandbox | https://developer-docs.amazon/sp-api/docs/sp-api-sandbox.md | 2026-09-09 | 2026-10-27 | Static pattern matching; support table |
322
+ | Get the market participation of a seller | https://developer-docs.amazon/sp-api/docs/get-seller-market-participation.md | 2026-09-09 | 2026-10-27 | Stores the seller can list in; role |
323
+ | SP-API Release Notes | https://developer-docs.amazon/sp-api/docs/sp-api-release-notes.md | 2026-10-26 | 2026-10-27 | PRODUCT and LISTING issue categories (2026-09-30); `parentageLevel` (2026-05-27); EPR reports |
324
+ | listingsItems_2021-08-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/listings-items-api-model/listingsItems_2021-08-01.json | pin | 2026-10-27 | Put parameters and body, submission response, status enum, issue categories, identifiers, sandbox cases |
325
+ | definitionsProductTypes_2020-09-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/product-type-definitions-api-model/definitionsProductTypes_2020-09-01.json | pin | 2026-10-27 | Search and get parameters, rates, sandbox placeholders |
326
+ | sellers.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/sellers-api-model/sellers.json | pin | 2026-10-27 | Participation fields, rate |
327
+ | listingsRestrictions_2021-08-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/listings-restrictions-api-model/listingsRestrictions_2021-08-01.json (and `main`, for the parameter list) | pin | 2026-10-27 | Parameters, reason codes, `productType` wording |
328
+ | catalogItems_2022-04-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/catalog-items-api-model/catalogItems_2022-04-01.json | pin | 2026-10-27 | `searchCatalogItems` parameters and rate |
329
+ | Seller Central help: Product detail page rules (G200390640) | capture `G200390640-v21` | v21 | 2026-10-14 | GTINs owned or licensed; no duplicate pages; product ID non-editable; new ASIN for another brand |
330
+ | Seller Central help: Build International Listings (G202121570) | capture `G202121570-v14` | v14 | 2026-10-14 | What the tool does and does not do |
331
+ | Seller Central help: Product image guide (G1881); Add product images and video (G200216080) | captures `G1881-v28`, `G200216080-v15` | v28, v15 | 2026-10-14 | Up to 24 hours to appear |
332
+ | Seller Central help: Product IDs (GTIN) exemption (G200426310) | https://sellercentral.amazon.com/help/hub/reference/external/G200426310 | none | not read | No capture; the content call is not used until the office rules |
333
+ | How to create Amazon product listings (sell.amazon.com) | https://sell.amazon.com/blog/amazon-product-listings | Apr 29, 2026 | 2026-10-27 | Brand Registry and approval conditions; the Add Product tabs |
334
+ | Amazon Brand Registry (sell.amazon.com) | https://sell.amazon.com/brand-registry | none shown | 2026-10-27 | Enrolment requirements; nothing decisive for an API creation |
335
+ | Seller Forums: Listing Lounge: Your GTIN Exemption Was Approved, But Now You Received An Error Message. What's Next? | https://sellercentral.amazon.com/seller-forums/discussions/t/a1257c84-e37a-439d-9c04-d731a0783edc | "2 years ago" | 2026-10-27 | Exemption spelling and wait; 5665, 5461, 8541, 8542 |
336
+ | GitHub: Cannot create new listings and ASINs (#2711) | https://github.com/amzn/selling-partner-api-models/issues/2711 | 2023-09-22 | 2026-10-27 | 8566 and 8572 after an accepted put |
337
+ | sell.amazon.com/blog/upc-codes; sell.amazon.com/learn/upc-codes | as named | none | 2026-10-27 | Not pages: 404 |
338
+
339
+ ## Open questions
340
+
341
+ 1. **ASIN assignment time.** No page read says how long a new item takes to get an ASIN or to become `BUYABLE` and `DISCOVERABLE`. *Settles:* the first real creation, read back on a cadence and timed.
342
+ 2. **Restrictions by brand.** The restrictions model says `productType` "When provided with the brand name" evaluates GTIN-exemption restrictions, but the operation has no brand parameter. *Settles:* Amazon's reference page or a developer support answer.
343
+ 3. **What a new item's product identifier looks like in the schema.** The inner properties of `externally_assigned_product_identifier` (the type field and its `enum`) and whether a store's schema still carries an older identifier attribute. *Settles:* the first `getDefinitionsProductType` for the seller's product type and store.
344
+ 4. **The preview's `identifiers` for a new item.** Whether a preview of a new item with no catalog match returns an empty `identifiers`, a would-be match, or an issue. *Settles:* the first real preview.
345
+ 5. **Does a preview run the identity checks?** Whether `4005007`, `4005008`, `100980` and the like come back on a preview, or only asynchronously after a write. The FAQ says the preview runs "the same checks that are done on production submissions" synchronously; the catalog-matching issues the AI sandbox drops (`research/method/listing-writes.md`, item 19) suggest some are judged against the live catalog. *Settles:* the first real preview with the seller's GTIN.
346
+ 6. **Seller Central brand codes through the API.** Whether 5461 and 5665 reach a Listings Items `issues` read under those codes. *Settles:* a real write that meets one.
347
+ 7. **The GTIN exemption page.** G200426310 was not read. *Settles:* the office's ruling on the content call, or a signed-in read by the seller or Jack.
348
+ 8. **WEEE and EPR in a listing.** Whether any EU store's schema names a WEEE or packaging-EPR attribute. *Settles:* `getDefinitionsProductType` for the seller's product type in each EU store named.
349
+ 9. **Children in the same request window as the parent.** Whether a child put sent before the parent's creation finishes processing is refused or held. The pages say only that the parent is created first. *Settles:* the first family creation, read back between the parent and the children.
350
+
351
+ ## Positions
352
+
353
+ - **P-listing-create-1.** The marketplaces a creation goes to are those the seller names, each checked against `getMarketplaceParticipations` (`isParticipating`, `hasSuspendedListings`), and each store's `defaultLanguageCode` and `defaultCurrencyCode` come from its row. Sources: sellers.json; Get the market participation of a seller.
354
+ - **P-listing-create-2.** Before a creation in a store, cx searches that store's catalog with `searchCatalogItems` by the product's identifier and `identifiersType`: an exact match is an existing item and gets an offer-only listing on that ASIN, after `getListingsRestrictions`; no match is a new item with product facts; several matches are told apart by product type, brand, title and parentage level through `getCatalogItem`. Sources: Building Listings Management Workflows Guide; Listings APIs FAQ; catalogItems_2022-04-01.json.
355
+ - **P-listing-create-3.** An offer-only listing is a put with `productType` `PRODUCT` and `requirements` `LISTING_OFFER_ONLY`, against the schema read with those values, naming the ASIN the catalog search found, and a vendor cannot list offer-only. Sources: Building Listings Management Workflows Guide; Submit Listings data; listingsItems_2021-08-01.json.
356
+ - **P-listing-create-4.** A new item's product type is found with `searchDefinitionsProductTypes` by `itemName` (the title, which may be combined with the description) or by `keywords`, never both, in the store's `searchLocale`, and a product type the API has not launched admits no new item with product facts, only offer-only listings. Sources: definitionsProductTypes_2020-09-01.json; Listings APIs FAQ; Building Listings Management Workflows Guide.
357
+ - **P-listing-create-5.** The schema for a creation is read for each store named, with one `marketplaceIds`, `requirements` `LISTING` (or `LISTING_PRODUCT_ONLY` for an item without sales terms yet), the seller's `sellerId`, and `parentageLevel` `NONE`, `PARENT` or `CHILD` for the listing being made, and its document is fetched from `schema.link.resource` within its seven days. Sources: definitionsProductTypes_2020-09-01.json; Retrieve a Product Type Definition; Building Listings Management Workflows Guide; Listings APIs FAQ.
358
+ - **P-listing-create-6.** What a value must look like is decided by the schema: `required` and its conditional `allOf`, the `enum` value (not its `enumNames` label), `enumDeprecated`, `maxLength` and `maxUtf8ByteLength`, `selectors`, `maxUniqueItems`, `editable`, and the seller-specific enums the `sellerId` read fills (brand names, fulfilment channel codes, shipping templates); the meta-schema's custom vocabulary is part of validation, so reading the schema as plain JSON Schema misses rules Amazon checks. Sources: Amazon Product Type Definitions Meta-Schema (v1); Building Listings Management Workflows Guide; definitionsProductTypes_2020-09-01.json; Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases; Submit Listings data.
359
+ - **P-listing-create-7.** A creation is `PUT /listings/2021-08-01/items/{sellerId}/{sku}` with one `marketplaceIds`, `includedData=identifiers,issues` and `issueLocale`, and a body of `productType`, `requirements` and `attributes` built from the seller's data in the schema's names and shapes, one store per request. Sources: listingsItems_2021-08-01.json; Submit Listings data; Listings APIs FAQ.
360
+ - **P-listing-create-8.** A put on a SKU that already exists replaces its content and drops what it omits, and a SKU cannot be changed after creation, so cx reads `getListingsItem` on the SKU before a creation and does not reuse a SKU the seller already lists. Sources: Create or fully update a listing; Listings Items API Issues Troubleshooting (4005013).
361
+ - **P-listing-create-9.** A new item's identity is a GTIN, UPC or EAN the seller owns from GS1 or is licensed by the prefix owner to use, in `externally_assigned_product_identifier` at the length its type takes, with the brand it is registered to, and the product ID cannot be edited after creation unless the item was created under a GTIN exemption. Sources: Product detail page rules (G200390640 v21); Listings Items API Issues Troubleshooting (90225, 90188, 4005007, 4005008, 100980).
362
+ - **P-listing-create-10.** A product without a GTIN is created only after the seller's GTIN exemption is approved in Seller Central, with `supplier_declared_has_product_identifier_exemption` set to `true` and the brand (and category) exactly as the approval names them. Sources: Listings APIs FAQ; Seller Forums "Listing Lounge: Your GTIN Exemption Was Approved…".
363
+ - **P-listing-create-11.** For a brand enrolled in Brand Registry, creating a detail page takes the brand's own account or one the brand authorised, and a refusal on brand grounds is answered through the brand's approval route, not by changing the brand to generic. Sources: How to create Amazon product listings (sell.amazon.com); Product detail page rules (G200390640 v21); Seller Forums "Listing Lounge…".
364
+ - **P-listing-create-12.** Text values are written in the store's language with the `language_tag` the store's schema allows, the schema's `locale` sets only display labels, and the price is a `purchasable_offer` in the store's currency with its `currency`, `audience` and `marketplace_id` selectors. Sources: definitionsProductTypes_2020-09-01.json; sellers.json; Manage purchasable offer; Submit Listings data.
365
+ - **P-listing-create-13.** A merchant-fulfilled offer is a `fulfillment_availability` record with `fulfillment_channel_code` `DEFAULT` and a `quantity` (and the handling time the schema offers), while an FBA offer names the seller's Amazon channel code without a quantity and needs the dangerous-goods and battery information Amazon requires for FBA, and the codes come from the seller-specific schema. Sources: Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases; Submit Listings data; Dangerous goods identification guide (as cited in attributes-and-browse-nodes.md).
366
+ - **P-listing-create-14.** Images are given as locations Amazon fetches (public HTTPS on S3, CloudFront or a third-party server, or a private S3 bucket Amazon's role may read), in the image attributes the store's schema offers, and private S3 content is treated as immutable, so new content there takes a new object key. Sources: Submit media attributes; Building Listings Management Workflows Guide.
367
+ - **P-listing-create-15.** The compliance attributes a store's schema names, GPSR in an EU store among them, are filled from the seller's own declarations at creation, store by store, since Amazon cannot determine them and wrong values block sale. Sources: Update: Support for GPSR compliance in Listings Items API (as cited in marketplaces-and-languages.md); Submitting manufacturer, Responsible Person, and warning and safety information (as cited there); Dangerous goods identification guide (as cited in attributes-and-browse-nodes.md); How to create Amazon product listings (sell.amazon.com).
368
+ - **P-listing-create-16.** A variation family is written parent first (`parentage_level` `parent`, `child_parent_sku_relationship` with `child_relationship_type` `variation`, a `variation_theme` the schema offers and not deprecated, no offer) and then each child (`parentage_level` `child`, the relationship with the parent's SKU in `parent_sku`, the parent's theme and the theme's attributes), each child repeating the family's product facts. Sources: Building Listings Management Workflows Guide; Submit Listings data; Retrieve a Product Type Definition.
369
+ - **P-listing-create-17.** A preview of a creation is the same put with `mode=VALIDATION_PREVIEW`, which runs production's synchronous checks without persisting anything and answers `VALID` or `INVALID` with its issues, and a required attribute the data does not fill comes back `INVALID` with an issue (such as `90220`, category `MISSING_ATTRIBUTE`) naming it in `attributeNames`. Sources: Preview errors before creating or fully updating a listing; Listings APIs FAQ; Listings Items API Issues Troubleshooting (90220); listingsItems_2021-08-01.json.
370
+ - **P-listing-create-18.** A write's `ACCEPTED` means the synchronous checks passed and the submission went downstream, `INVALID` means it was not accepted, and the `submissionId` identifies it; issues from the downstream processing, such as a conflict with another catalog item, appear only on a later `getListingsItem`. Sources: Building Listings Management Workflows Guide; Listings APIs FAQ; listingsItems_2021-08-01.json.
371
+ - **P-listing-create-19.** A creation is done when `getListingsItem` for that store shows a summary with an ASIN, `status` holding `BUYABLE` and `DISCOVERABLE`, and no `ERROR` issue; the FAQ reads an empty summary as a submission that failed and did not match an ASIN, and no page states how long a creation takes to reach an ASIN or those statuses. Sources: Listings APIs FAQ; listingsItems_2021-08-01.json; Manage Product Listings with the Selling Partner API.
372
+ - **P-listing-create-20.** The static sandbox answers a creation by pattern (an empty body `ACCEPTED`, fixed `VALIDATION_VALID` and `VALIDATION_INVALID` SKUs, one product type, a placeholder schema link), so it proves a request's path, signing and shape, never the product type, the schema, the identity or what Amazon would answer for the seller's product. Sources: Selling Partner API Sandbox; listingsItems_2021-08-01.json; definitionsProductTypes_2020-09-01.json.
373
+ - **P-listing-create-21.** Build International Listings is a Seller Central tool that creates offers where the same ASIN exists in both stores and attempts translated pages it does not guarantee, so a creation in each named store goes through that store's own schema, preview and put. Sources: Build International Listings (G202121570 v14); Listings APIs FAQ.
374
+ - **P-listing-create-22.** `getListingsRestrictions` is read by ASIN, so it applies to an offer-only listing, and a new item's approval requirement shows as a `QUALIFICATION_REQUIRED` issue on the preview or the write. Sources: listingsRestrictions_2021-08-01.json; Get listings restrictions for an item in the catalog; listingsItems_2021-08-01.json.
375
+ - **P-listing-create-23.** Amazon keeps no history of a listing, so a creation is a change whose before is empty, and what cx sent and what Amazon answered are kept only in the change log. Sources: listingsItems_2021-08-01.json; Listings Items API (as cited in listing-writes.md).
376
+ - **P-listing-create-24.** A conflict issue is answered as its own text says: `4005011` by changing the submitted value to the catalog's or by contacting Amazon to change the catalog's; `4005033` by reverting to the original value and resubmitting, with a support case to dispute the original; `101165` by making the SKU, external ID and ASIN unique and resubmitting, with support where the duplicate is in Amazon's catalog. Sources: Listings Items API Issues Troubleshooting.
377
+
378
+ ### The seat's own (not for a skill)
379
+
380
+ - [seat] For GL's trial, the most likely blocker is identity rather than content: a GTIN not registered to the brand on the listing, or a brand in Brand Registry whose account is not the one connected. Both show only on a real preview or a real write (open question 5).
381
+ - [seat] The preview is the cheap place to learn a store's requirements: a deliberately thin preview lists what the store's product type requires, but the schema already lists it, so the preview's value is in the checks the schema cannot express (pricing, identity, catalog conflicts).
382
+ - [seat] A family's children can be previewed before the parent exists, but whether a child's preview judges `parent_sku` against a parent not yet created is not known (open question 9); parent first in both preview and write is the safe order.
383
+ - [seat] The sell.amazon.com guide's "up to five bullets" and "up to nine photos" are Seller Central form figures, not the schema's; they are left in *Facts for human readers only* in `research/README.md`.
384
+
385
+ ## Verification
386
+
387
+ Checked 2026-10-27 by the research seat. Method: every quotation in sections A–L was string-matched against the page text downloaded in this session (the developer pages in `.md` form, the five model files at the pin parsed with `jq`, the help-page captures, and the sell.amazon.com page text); the forum post and the GitHub issue were read through WebFetch and are quoted from its extract. The practitioner entries marked "not opened" were not read beyond a search result and carry no position. No Amazon API host or Keepa host was called.
388
+
389
+ Still unverified: the Seller Forums post's staff badge (the account is named "Rose_Amazon", but the fetched text shows no badge); open questions 1–9.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: listing-create
3
+ description: "Creating an Amazon listing from the seller's product data in the marketplaces the seller names: the seller's stores, telling a new item from an existing ASIN, the product type and each store's schema, the request built from the seller's data, the preview, the write on the seller's word, the read-back until the listing is buyable and discoverable, and variation families. For putting a new product, or a new offer, on Amazon."
4
+ ---
5
+
6
+ Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
7
+
8
+ ## Stores
9
+
10
+ - The stores are the ones the seller names, each found in `GET /sellers/v1/marketplaceParticipations` with `participation.isParticipating` true, and each row gives the store's `marketplace.id`, `defaultLanguageCode` and `defaultCurrencyCode` (P-listing-create-1; P-sp-api-access-1).
11
+ - A row with `hasSuspendedListings` true is an account-level Inactive status in that store, which would leave every listing there unbuyable (P-sp-api-access-14; P-listing-create-1).
12
+ - Each store is a regional origin of its own (P-marketplaces-and-languages-2), and the seller id in each path comes from the reply the door names, never from the seller (P-sp-api-access-3).
13
+ - Build International Listings is Seller Central's, not the API's: a creation in each store goes through that store's schema, preview and put (P-listing-create-21).
14
+
15
+ ## New item or existing ASIN
16
+
17
+ - `GET /catalog/2022-04-01/items` with `identifiers`, `identifiersType` and the store's `marketplaceIds` decides it: an exact match is an existing ASIN, no match is a new item, and several matches are told apart by product type, brand, title and parentage through `getCatalogItem` (P-listing-create-2).
18
+ - An existing ASIN gets an offer-only listing: `GET /listings/2021-08-01/restrictions` with the `asin` first, then a put with `productType` `PRODUCT` and `requirements` `LISTING_OFFER_ONLY` naming that ASIN (P-listing-create-3; P-listing-create-22).
19
+ - A product already in Amazon's catalog is never given a second detail page (P-listing-create-9).
20
+ - `GET /listings/2021-08-01/items/{sellerId}/{sku}` is read before a creation, because a put on a SKU that exists replaces it and a SKU cannot be changed afterwards (P-listing-create-8).
21
+
22
+ ## Product type and schema
23
+
24
+ - A new item's product type comes from `GET /definitions/2020-09-01/productTypes` with `itemName` (the title, which may be combined with the description) or `keywords`, never both, and the store's `marketplaceIds` (P-listing-create-4).
25
+ - A product type the API has not launched admits no new item with product facts (P-listing-create-4).
26
+ - The schema is `GET /definitions/2020-09-01/productTypes/{productType}` once per store, with that one `marketplaceIds`, `requirements=LISTING`, the `sellerId` and the `parentageLevel` of the listing being made, and its document is fetched from `schema.link.resource` before the link expires (P-listing-create-5).
27
+ - What a value must look like is the schema's: `required` and its conditionals, the `enum` value, `enumDeprecated`, the length keywords, `selectors`, `maxUniqueItems` and the seller-specific enums the `sellerId` fills (P-listing-create-6).
28
+ - The schema's own vocabulary is part of validation; reading it as plain JSON Schema misses rules Amazon checks (P-listing-create-6).
29
+
30
+ ## Request
31
+
32
+ - A creation is `PUT /listings/2021-08-01/items/{sellerId}/{sku}?marketplaceIds=<one>&includedData=identifiers,issues&issueLocale=<locale>` with a body of `productType`, `requirements` and `attributes` in the schema's names and shapes, one store per request (P-listing-create-7).
33
+ - The request carries only truthful values that the seller's data or the seller supports, and compliance declarations are the seller's own, since Amazon cannot determine them (P-listing-create-9; P-listing-create-15; P-attributes-and-browse-nodes-16).
34
+ - references/request.md holds identity, language, price, fulfilment, images and compliance.
35
+
36
+ ## Preview and write
37
+
38
+ - A preview is the same put with `mode=VALIDATION_PREVIEW`; it persists nothing, so it is sent as any read is, and the put without the mode waits for the seller's word (P-listing-writes-5; P-listing-create-17).
39
+ - A preview answers `VALID` or `INVALID` with `issues` (P-listing-create-17).
40
+ - A required attribute the data does not fill answers `INVALID`, with an issue such as `90220`, category `MISSING_ATTRIBUTE`, naming it in `attributeNames` (P-listing-create-17).
41
+ - The write's `ACCEPTED` means the synchronous checks passed and processing began, `INVALID` means nothing was taken, and `submissionId` names the submission (P-listing-create-18).
42
+ - Issues from downstream processing, such as a conflict with another catalog item, appear only on a later `getListingsItem` (P-listing-create-18).
43
+
44
+ ## Read-back
45
+
46
+ - `GET /listings/2021-08-01/items/{sellerId}/{sku}` with `includedData=summaries,attributes,issues,offers,fulfillmentAvailability,relationships` is read again until it settles (P-listing-create-19).
47
+ - The creation is done when the store's summary carries an ASIN, `status` holds `BUYABLE` and `DISCOVERABLE`, and no issue is `ERROR` (P-listing-create-19).
48
+ - Amazon's FAQ reads an empty summary as a submission that failed and did not match an ASIN, and no page states how long a creation takes (P-listing-create-19).
49
+ - Then `getCatalogItem` on that ASIN shows what shoppers see, which can differ from what was sent (P-listing-writes-7).
50
+
51
+ ## Families
52
+
53
+ - A variation family is written parent first, then each child with the parent's SKU and theme (P-listing-create-16).
54
+ - references/family.md holds each listing's attributes and how a family is read back.
55
+
56
+ ## Log
57
+
58
+ - A creation is a change logged by listing-change-log whose Before is empty, because Amazon keeps no history of a listing (P-listing-create-23).
59
+ - Its Request and receipt hold the put as sent and each store's `submissionId`, `status` and `issues` (P-listing-writes-8).
60
+
61
+ ## Sandbox
62
+
63
+ - A static sandbox answer proves a request's path, signing and shape, never the product type, the schema, the identity or Amazon's verdict on the seller's product (P-listing-create-20).
64
+ - references/answers.md holds the issues that name identity, brand and catalog conflicts with the resolution each names, and the sandbox's fixed answers.
65
+
66
+ ## References
67
+
68
+ [request.md](references/request.md): identity, language, price, fulfilment, images, compliance. [family.md](references/family.md): parent and children. [answers.md](references/answers.md): issues and the sandbox.
@@ -0,0 +1,18 @@
1
+ # What Amazon answers to a creation
2
+
3
+ ## Identity and catalog
4
+
5
+ - `4005007` is an identifier not registered for the brand given; it is answered with proof of affiliation such as a GS1 certificate or licence (P-listing-create-9).
6
+ - `4005008` is an identifier restricted or not registered in GS1 (P-listing-create-9).
7
+ - `100980` is a barcode already on another ASIN, looked up through the Catalog Items API (P-listing-create-9).
8
+ - `4005013` is an item already in the seller's catalog under another SKU (P-listing-create-8).
9
+ - `90225` and `90188` are an identifier of the wrong length or checksum: 12 for UPC, 13 for EAN, 14 for GTIN (P-listing-create-9).
10
+ - An approval requirement on a new item shows as a `QUALIFICATION_REQUIRED` issue on the preview or the write (P-listing-create-22).
11
+ - `4005011` is a value that conflicts with another catalog item: the submitted value is changed to the catalog's, or Amazon is contacted to change the catalog's (P-listing-create-24).
12
+ - `4005033` is a value that cannot be edited: it is reverted to the original and resubmitted, and a support case disputes an original that is wrong (P-listing-create-24).
13
+ - `101165` is SKU, external ID and ASIN matching several products: they are made unique and resubmitted, and support resolves a duplicate in Amazon's catalog (P-listing-create-24).
14
+
15
+ ## Sandbox
16
+
17
+ - The static sandbox answers a put by pattern: an empty body `ACCEPTED`, SKU `VALIDATION_VALID` `VALID`, SKU `VALIDATION_INVALID` `INVALID` with a canned `90220`, and `BadSKU` 400 (P-listing-create-20).
18
+ - Its product type search answers one product type, and its schema link is a placeholder, not a schema (P-listing-create-20).
@@ -0,0 +1,10 @@
1
+ # A variation family
2
+
3
+ - The parent's schema is read with `parentageLevel=PARENT` and each child's with `parentageLevel=CHILD`, where the theme's attributes and `parent_sku` appear as required (P-listing-create-5; P-listing-create-16).
4
+ - The parent carries `parentage_level` `parent`, `child_parent_sku_relationship` with `child_relationship_type` `variation`, and a `variation_theme` the schema offers, and no offer, since a parent is not buyable (P-listing-create-16).
5
+ - Each child carries `parentage_level` `child`, `child_parent_sku_relationship` with `child_relationship_type` `variation` and the parent's SKU in `parent_sku`, the parent's `variation_theme`, and the theme's attributes (P-listing-create-16).
6
+ - Each child repeats the family's product facts (P-listing-create-16).
7
+ - A theme flagged `enumDeprecated` is not used for a new family (P-listing-create-16; P-variations-2).
8
+ - A child that differs from its siblings in function, generation or model gets its own detail page, not a place in the family (P-variations-4).
9
+ - A standalone listing's schema is read with `parentageLevel=NONE` (P-listing-create-5).
10
+ - A family has taken when `issues` are empty and Catalog `relationships` show the intended parent, children and theme (P-variations-10).
@@ -0,0 +1,44 @@
1
+ # The request, from the seller's data
2
+
3
+ ## Identity
4
+
5
+ - A new item's identifier is a GTIN, UPC or EAN the seller bought from GS1 or is licensed by the prefix owner to use, in `externally_assigned_product_identifier` at the length its type takes (P-listing-create-9).
6
+ - The brand is the one the identifier is registered to; another brand's product gets its own ASIN, never an edit of an existing one (P-listing-create-9; P-listing-create-11).
7
+ - The product ID cannot be edited after creation unless the item was created under a GTIN exemption (P-listing-create-9).
8
+ - A product without a GTIN is created only after the seller's exemption is approved in Seller Central, with `supplier_declared_has_product_identifier_exemption` `true` and the brand and category spelled exactly as the approval names them (P-listing-create-10).
9
+ - A brand enrolled in Brand Registry is created by the brand's own account or one the brand authorised, and a refusal on brand grounds goes through the brand's approval route, not a change of brand (P-listing-create-11; P-brand-protection-and-catalog-contribution-2).
10
+ - The `sellerId` read of the schema fills the brand names associated with the seller (P-listing-create-5).
11
+
12
+ ## Language
13
+
14
+ - A text value is an array of objects with `value`, `language_tag` and `marketplace_id` (P-listing-writes-4).
15
+ - The tag is the one the store's schema allows under `$defs.language_tag`, written with an underscore, as in `en_US` (P-marketplaces-and-languages-7; P-title-30).
16
+ - The schema's `locale` sets display labels only, not the language of the values written (P-listing-create-12).
17
+ - Text is written for each store in that store's language, not copied across stores (P-marketplaces-and-languages-8; P-listing-writes-22).
18
+
19
+ ## Price
20
+
21
+ - The price is `purchasable_offer` with `currency`, `audience` and `marketplace_id`, and `our_price` as `[{"schedule": [{"value_with_tax": <amount>}]}]`, in the store's `defaultCurrencyCode` (P-listing-create-12; P-listing-create-1).
22
+ - A preview with the price attributes also returns pricing issues (P-listing-create-17).
23
+
24
+ ## Fulfilment
25
+
26
+ - A merchant-fulfilled offer is a `fulfillment_availability` record with `fulfillment_channel_code` `DEFAULT` and a `quantity` (P-listing-create-13).
27
+ - An FBA offer names the seller's Amazon channel code without a quantity, and needs the dangerous-goods and battery information Amazon requires for FBA (P-listing-create-13).
28
+ - The channel codes and shipping templates are the seller-specific schema's, and a template is written by its `enum` key (P-listing-create-13; P-inventory-and-fulfillment-15).
29
+
30
+ ## Images
31
+
32
+ - Images are given as locations Amazon fetches: public HTTPS on S3, CloudFront or a third-party server, or a private S3 bucket Amazon's role may read (P-listing-create-14).
33
+ - Amazon fetches media only from a location it can reach with the permissions Submit media attributes names, and a file in the seller's tree is no such location (P-listing-create-14; P-images-and-video-5).
34
+ - They go in the locator attributes the store's schema offers, with `media_location` (P-images-and-video-4; P-listing-create-14).
35
+ - Private S3 content is treated as immutable, so new content there takes a new object key (P-listing-create-14).
36
+ - An image applies to the ASIN in every store where it exists (P-listing-writes-10).
37
+ - An image of a photorealistic AI-generated person carries the `contains-synthetic-performer` tag (P-images-and-video-25).
38
+ - Main-block video is a Seller Central task (P-images-and-video-9).
39
+
40
+ ## Compliance
41
+
42
+ - The compliance attributes a store's schema names, GPSR in an EU store among them, are filled from the seller's own declarations, store by store (P-listing-create-15; P-marketplaces-and-languages-11).
43
+ - Dangerous goods, battery, safety data sheet, Prop 65 and CPSIA values come from the seller, since Amazon cannot determine them (P-attributes-and-browse-nodes-16).
44
+ - A Prop 65 warning goes on child SKUs, not the parent (P-attributes-and-browse-nodes-18).