cx-listing-playbook 0.4.0 → 0.5.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 +3 -3
- package/README.zh-CN.md +3 -3
- package/package.json +12 -2
- package/research/README.md +6 -6
- package/research/angles/competitor-set.md +1 -1
- package/research/angles/listing-content-and-health.md +2 -2
- package/research/angles/paid-keywords.md +1 -1
- package/research/angles/price-position.md +1 -1
- package/research/angles/reviews-and-qa.md +2 -2
- package/research/angles/seasonality-and-events.md +2 -2
- package/research/elements/description.md +2 -2
- package/research/elements/search-terms.md +1 -1
- package/research/elements/variations.md +3 -3
- package/research/method/listing-writes.md +1 -1
- package/research/method/report-lifecycle.md +2 -2
- package/skills/listing-change-log/SKILL.md +1 -1
- package/skills/listing-change-log/references/record.md +1 -1
- package/skills/listing-create/SKILL.md +2 -2
- package/skills/listing-review/references/watch.md +1 -1
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@ This playbook teaches cx how to work on your Amazon listings: creating new ones,
|
|
|
2
2
|
|
|
3
3
|
With it, cx:
|
|
4
4
|
|
|
5
|
-
- Creates listings in the stores you name, from your own words and your product's data. It
|
|
5
|
+
- Creates listings in the stores you name, from your own words and your product's data. It reads each one back until buyers can find it and buy it.
|
|
6
6
|
- Reviews a listing at each step from search to purchase, says what has changed since it last looked, and reads what Amazon itself reports about the listing.
|
|
7
|
-
- Proposes a change with its reasons and the figures behind them
|
|
7
|
+
- Proposes a change with its reasons and the figures behind them.
|
|
8
8
|
- Keeps a record of every change: before and after, what was expected, and Amazon's receipt.
|
|
9
9
|
- Tells you, once enough time has passed, whether a change worked, did not, or cannot be told yet.
|
|
10
10
|
- Explains the Buy Box: whether your offer holds it, why not, and which causes you can fix in your store.
|
|
@@ -18,7 +18,7 @@ To have cx keep watching a listing for you, also install cx-listing-watch.
|
|
|
18
18
|
|
|
19
19
|
## What it uses
|
|
20
20
|
|
|
21
|
-
- **Amazon SP-API:** your Amazon seller account, connected on the Amazon SP-API plugin. cx reads your listings, offers and reports there, and changes
|
|
21
|
+
- **Amazon SP-API:** your Amazon seller account, connected on the Amazon SP-API plugin. cx reads your listings, offers and reports there, and changes your listings there.
|
|
22
22
|
- **Keepa,** where you have it: price and rank history, and your competitors' listings.
|
|
23
23
|
|
|
24
24
|
Each is its own plugin, and its page gives its price.
|
package/README.zh-CN.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
装上之后,cx 会:
|
|
4
4
|
|
|
5
|
-
- 按你的描述和产品资料,在你指定的站点创建 listing
|
|
5
|
+
- 按你的描述和产品资料,在你指定的站点创建 listing,并回查到买家能搜到、能购买为止。
|
|
6
6
|
- 从搜索到下单逐步检查一条 listing,说明它比上次检查时有什么变化,并读取亚马逊对这条 listing 给出的信息。
|
|
7
|
-
-
|
|
7
|
+
- 提出修改建议,附上理由和依据的数据。
|
|
8
8
|
- 每次修改都留一份记录:改前改后、预期效果和亚马逊的回执。
|
|
9
9
|
- 等观察期足够后,告诉你这次修改已见效、未见效,还是暂时无法确定。
|
|
10
10
|
- 分析 Buy Box:你的报价有没有拿到、为什么没拿到,以及哪些原因能在店铺里解决。
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
|
|
19
19
|
## 用到的数据
|
|
20
20
|
|
|
21
|
-
- **Amazon SP-API**:你的亚马逊卖家账户,在 Amazon SP-API 插件里连接。cx 在这里读取你的 listing
|
|
21
|
+
- **Amazon SP-API**:你的亚马逊卖家账户,在 Amazon SP-API 插件里连接。cx 在这里读取你的 listing、报价和报告,也在这里修改 listing。
|
|
22
22
|
- **Keepa**(如果你装了):价格和排名的历史,以及竞品的 listing。
|
|
23
23
|
|
|
24
24
|
两者各是一个插件,价格见各自的页面。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cx-listing-playbook",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.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",
|
|
@@ -50,7 +50,17 @@
|
|
|
50
50
|
"listing-review": {
|
|
51
51
|
"zh": "检查一条亚马逊 listing:表现如何、有什么变化、该改什么。"
|
|
52
52
|
}
|
|
53
|
-
}
|
|
53
|
+
},
|
|
54
|
+
"builds": [
|
|
55
|
+
{
|
|
56
|
+
"on": "cx-amazon-sp-api",
|
|
57
|
+
"need": "required"
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"on": "cx-keepa",
|
|
61
|
+
"need": "optional"
|
|
62
|
+
}
|
|
63
|
+
]
|
|
54
64
|
},
|
|
55
65
|
"homepage": "https://github.com/comchatx/cx-listing-playbook#readme",
|
|
56
66
|
"repository": {
|
package/research/README.md
CHANGED
|
@@ -276,8 +276,8 @@ Each position is one sentence, followed by the P-ids that carry it and the names
|
|
|
276
276
|
- **C15.** An image change is logged as applying to the ASIN in every store where it exists, notes any country-specific image set, and the seller hears this before deciding. — P-images-and-video-6, 21; P-marketplaces-and-languages-3. [official] Listings APIs FAQ.
|
|
277
277
|
- **C16.** Every change, read and effect series names exactly one `marketplace_id`, and effects are never summed across stores. — P-marketplaces-and-languages-1. [official] Marketplace IDs; sellerSalesAndTrafficReport.json.
|
|
278
278
|
- **C17.** Before a price, sale or offer change, cx asks whether a Build International Listings connection includes the store, and tells the seller Amazon does not say whether a hand edit in a target store survives later syncs. — P-marketplaces-and-languages-4, 6. [official] Build International Listings; Build International Listings price rules; Global Offer Manager.
|
|
279
|
-
- **C18.** The ad bidding strategy for the window and
|
|
280
|
-
- **C19.** A family change records the whole family from both sides, and deleting or moving a parent or child or changing a theme
|
|
279
|
+
- **C18.** The ad bidding strategy for the window and whether bids are held fixed are recorded at baseline, and a title change on an advertised ASIN notes that ad creative shows the title. — P-paid-keywords-16, 18; P-title-27. [official] Sponsored Products 3.0 OpenAPI; Sponsored Products rule-based bidding overview.
|
|
280
|
+
- **C19.** A family change records the whole family from both sides, and deleting or moving a parent or child or changing a theme names its reversal path, since the removal path deletes listings and a parent's deletion unlinks every child. — P-variations-1, 3, 11. [official] Building Listings Management Workflows Guide; listingsItems_2021-08-01.json; catalogItems_2022-04-01.json.
|
|
281
281
|
- **C20.** A delete is logged as irreversible with what it takes with it, and no inactive or unfamiliar SKU is deleted, closed or "cleaned up" without first reading why it is inactive, its FBA units and their stranded reason. — P-listing-writes-16, 17; P-inventory-and-fulfillment-5. [official] Delete a listing; Fix stranded inventory; Stranded inventory required removals.
|
|
282
282
|
- **C21.** Several changes made together are logged as one combined change, and the verdict is about the combination. — P-effect-measurement-5. [official] Save time by running simultaneous experiments on brand listing content. [research] Controlled experiments on the web.
|
|
283
283
|
- **C22.** The seller's own promotions, deals and coupons in either window are logged from the Promotions API, joined to the performance reports through `promotionsApiMappingId`, and creating or editing them is a Seller Central action because the API is read-only. — P-seasonality-and-events-6, 21, 22; P-price-position-8. [official] Promotions API; promotions_2025-12-01.json; Performance Reports.
|
|
@@ -373,7 +373,7 @@ Each position is one sentence, followed by the P-ids that carry it and the names
|
|
|
373
373
|
- **S15.** Published rates are defaults only; the `x-amzn-RateLimit-Limit` header is the plan in force, and no fixed rate is quoted. — P-sp-api-access-11; P-competitor-set-29; P-report-lifecycle-10. [official] Usage Plans and Rate Limits; Listings Items API Rate Limits; Catalog Items API Rate Limits.
|
|
374
374
|
- **S16.** A document link is fetched in the step it is issued and never printed, stored or reused, a `GZIP` document is decompressed, and a Data Kiosk document relies on `Content-Encoding`. — P-report-lifecycle-4, 5. [official] reports_2021-06-30.json; dataKiosk_2023-11-15.json; Building Data Kiosk workflows guide.
|
|
375
375
|
- **S17.** Every landed document is kept as a file in the seller's tree (never `/tmp`) with its report or query id, type, store, data range and processing times, so a change log can cite it, and readers key on column names and strip a byte order mark. — P-report-lifecycle-17, 24, 25; P-triggers-6; P-competitor-set-7. [official] Report Type Values; Retrieve a report; Data Protection Policy; Reports API.
|
|
376
|
-
- **S18.**
|
|
376
|
+
- **S18.** `getReportSchedules` is read before a report schedule is created or replaced, because a new schedule silently replaces an existing one. — P-report-lifecycle-11. [official] reports_2021-06-30.json; Schedule and retrieve reports.
|
|
377
377
|
- **S19.** cx cancels only its own report while `IN_QUEUE`, and its own Data Kiosk query while `IN_QUEUE` or `IN_PROGRESS`. — P-report-lifecycle-12. [official] reports_2021-06-30.json; dataKiosk_2023-11-15.json.
|
|
378
378
|
- **S20.** A Data Kiosk query is read with `getQuery` to a terminal status, `dataDocumentId` is data, `errorDocumentId` Amazon's explanation, and `DONE` with neither means no data for that range. — P-report-lifecycle-13. [official] Verify that query processing is complete; Data Kiosk API.
|
|
379
379
|
- **S21.** A Data Kiosk result is complete only when no `pagination.nextToken` remains, each page being a new `createQuery` with that token, and an identical pending query is never resubmitted. — P-report-lifecycle-14, 15. [official] dataKiosk_2023-11-15.json; Data Kiosk API; Building Data Kiosk workflows guide.
|
|
@@ -394,7 +394,7 @@ Each position is one sentence, followed by the P-ids that carry it and the names
|
|
|
394
394
|
- **T6.** Amazon's push signals reach only an AWS destination, so a watch from the box pulls state on its cadence, a notification may arrive more than once and out of order, and `ANY_OFFER_CHANGED` "External" is not read as a new seller. — P-triggers-12, 21; P-offer-competition-and-hijackers-13; P-account-health-11; P-brand-protection-and-catalog-contribution-9. [official] Notification Type Values; notifications.json; Set up notifications using the Amazon EventBridge workflow; Set up notifications using the Amazon Simple Queue Service workflow.
|
|
395
395
|
- **T7.** An account watch reads the seller-performance report and `getMarketplaceParticipations` on the seller's cadence. — P-account-health-11. [official] Performance Reports; sellers.json.
|
|
396
396
|
- **T8.** A stock watch reads stock-out precursors (restock alerts, days of supply, below-minimum levels, capacity blocks) and stranded units as "stock risk", never as a listing problem, and warns before a stock-out lands in a planned test window. — P-inventory-and-fulfillment-6, 7. [official] Fulfillment by Amazon (FBA) Reports; Low-inventory-level fee; Inventory performance; FBA capacity limits.
|
|
397
|
-
- **T9.** The competitor set is the seller's named rivals plus Amazon's `similarItems`,
|
|
397
|
+
- **T9.** The competitor set is the seller's named rivals plus Amazon's `similarItems`, which are Amazon's candidates and not the seller's own set; cx confirms what each is before tracking it. — P-triggers-15; P-competitor-set-3. [official] getCompetitiveSummary reference; SP-API Release Notes.
|
|
398
398
|
- **T10.** The set is frozen per window, and a re-pick is a new, dated version of the set. — P-competitor-set-6; P-competitor-discovery-13. [research] Brodersen et al.
|
|
399
399
|
- **T11.** Competitor data drawn from one seller's connection is used only for that seller. — P-competitor-set-20. [official] Acceptable Use Policy 4.4 and 4.6.
|
|
400
400
|
- **T12.** Seller Central-only tools (MYE, RLC, View Change History, Enhance, Seller Assistant, VOC, A+ performance, Store insights) are not read by cx: they arrive as files the seller puts in the tree, and cx never claims to have read them itself. — P-seller-central-only-tools-1, 5, 6, 7; P-a-plus-content-17; P-brand-story-and-store-12. [official] Analytics Reports; Create a listing experiment; Seller Assistant help page.
|
|
@@ -541,7 +541,7 @@ Every figure below was read on 2026-10-14 on the page named. No skill states the
|
|
|
541
541
|
### For Jack's word
|
|
542
542
|
|
|
543
543
|
- **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.)
|
|
544
|
-
- **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
|
|
544
|
+
- **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 is a real submission: Amazon validates and processes it and may answer `INVALID`, and whether the listing becomes buyable or discoverable shows only on the later read-back (R6, R8).
|
|
545
545
|
- **Acceptable Use Policy.** How does AUP 4.3 bear on Keepa use and on recommending third-party tools?
|
|
546
546
|
- **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.)
|
|
547
547
|
- **Selling Partner plugin.** Is the Selling Partner plugin in scope for the box?
|
|
@@ -556,7 +556,7 @@ Every figure below was read on 2026-10-14 on the page named. No skill states the
|
|
|
556
556
|
- **"ASIN + keyword" check.** May cx test whether an ASIN is found for a keyword on the public site, given the Conditions of Use and robots.txt (P-search-rank-and-volume-7, search-terms OQ6)?
|
|
557
557
|
- **Economics query.** May a Data Kiosk Economics query be run under Jack's word to settle ad dating and role?
|
|
558
558
|
- **Images.** Can the box model view images, and may it fetch the image CDN under PRODUCT.md §7? (The office.)
|
|
559
|
-
- **Controlled tests on a live ASIN.** A description-token
|
|
559
|
+
- **Controlled tests on a live ASIN.** Ruled by ComChatX decision D233 (2026-10-25): when to ask the seller is the model's judgement. A description-token test changes that ASIN's description while it runs. A search-terms-tail test changes data hidden from shoppers and the ASIN's search eligibility, with indexing not guaranteed.
|
|
560
560
|
- **Category style guides and the calendar.** Should dated category style guides and a machine-readable event calendar be kept in the tree?
|
|
561
561
|
- **Operator routine and help-page re-reads.** Who owns the operator routine, including a periodic re-read of the help-page captures?
|
|
562
562
|
|
|
@@ -458,7 +458,7 @@ The token cost of each read lives in the keepa skill and in the reply's own cons
|
|
|
458
458
|
|
|
459
459
|
1. **P-competitor-set-1**: A competitor set is a written, dated list of ASINs chosen for the same shopper need: the same core search terms, the same use or format, and the same price band. — Product Opportunity Explorer niche pages (sell.amazon.com blog; Seller Forums "All about niches"); Amazon Competitor Analysis (Ecombrainly); Amazon Share of Voice (SalesDuo); Mapping Online Consumer Search (Kim et al.)
|
|
460
460
|
2. **P-competitor-set-2**: For a brand-registered seller, the first evidence of who competes on a term is Amazon's Search Terms report (top clicked ASINs with click and conversion share), read beside Search Query Performance's totals. — Analytics Reports; sellingPartnerSearchTermsReport.json; Amazon Brand Analytics blog
|
|
461
|
-
3. **P-competitor-set-3**: Amazon's `similarItems` from `getCompetitiveSummary`
|
|
461
|
+
3. **P-competitor-set-3**: Amazon's `similarItems` from `getCompetitiveSummary` are Amazon's candidates for a set, not the seller's own set, and cx says which set it used. — getCompetitiveSummary reference; SP-API Release Notes
|
|
462
462
|
4. **P-competitor-set-4** (amended in the gap fill): A product bought together with ours (Market Basket, frequently bought together) enters the competitor set only if it also passes the substitute test of P-competitor-set-1; co-purchase alone neither admits it nor rules it out. — Analytics Reports; sellingPartnerMarketBasketAnalysisReport.json; Market Basket Analysis dashboard (help); Amazon Brand Analytics blog; Inferring Networks of Substitutable and Complementary Products
|
|
463
463
|
5. **P-competitor-set-5**: cx does not cite the Brand Analytics "Item Comparison" or "Alternate Purchase" reports; Amazon removed them. — SP-API Deprecation Schedule
|
|
464
464
|
6. **P-competitor-set-6**: The set is not changed inside an open observation window; a re-pick is a new, dated version of the set. — Amazon Share of Voice (SalesDuo); Amazon Competitor Analysis (Ecombrainly); Inferring causal impact (Brodersen et al.)
|
|
@@ -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.** `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
|
|
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 is a real submission: Amazon validates and processes it and may answer `INVALID`, and whether the listing becomes buyable or discoverable shows only on the later read-back (P-listing-create-18, 19). 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
|
-
- 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
|
|
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 is a real submission: Amazon validates and processes it and may answer `INVALID`, and whether the listing becomes buyable or discoverable shows only on the later read-back (P-listing-create-18, 19).
|
|
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.
|
|
@@ -567,7 +567,7 @@ The package states none of the following figures: windows, retention, ranges, lo
|
|
|
567
567
|
15. **P-paid-keywords-15.** Before cx reads a fall in sessions, ad impressions or orders as a content problem, it checks whether the changed SKU lost the Featured Offer or went out of stock in the window. Amazon shows Sponsored Products ads only for a product that is in stock and the Featured Offer, and a lost Featured Offer stops the ads whatever the copy says. (How to improve your product detail page for advertising; Best practices for your Sponsored Products ads; Sponsored Products and Buy Box, staff reply; Sponsored Products 3.0 OpenAPI `AD_NOT_IN_BUYBOX`; Eligibility 3.0 OpenAPI; Rel.ai, Your Ads Stopped Showing …)
|
|
568
568
|
16. **P-paid-keywords-16.** listing-change-log records, at the baseline, the bidding strategy, placement adjustments and any bid or budget rules of every campaign that advertises the changed SKU. If no Ads source exists, it records the seller's own answer to that question. (Sponsored Products 3.0 OpenAPI `SponsoredProductsBiddingStrategy`, `SponsoredProductsPlacementBidding`; Sponsored Products rule-based bidding overview)
|
|
569
569
|
17. **P-paid-keywords-17.** When those campaigns run dynamic bids (up and down, or down only) or rule-based bidding, effect-review does not subtract the ad-driven change in exposure as a confounder. Those strategies move bids with Amazon's estimate of conversion likelihood, so part of the ad response can be a consequence of the listing change. Subtracting a consequence of the treatment biases the estimate of its total effect. effect-review counts as a confounder only the ad changes a person made: manual bid, budget, target, negative, campaign-state and strategy edits. (Sponsored Products 3.0 OpenAPI; Guide to dynamic bidding - up and down; Sponsored Products rule-based bidding overview; Cinelli, Forney & Pearl, A Crash Course in Good and Bad Controls; Angrist & Pischke 2009 §3.2.3 as quoted there)
|
|
570
|
-
18. **P-paid-keywords-18.** effect-review's verdict says which effect it measured. Under dynamic or rule-based bidding it is the change's total effect, ads' automatic response included. Under fixed bids (`MANUAL`) with no manual ad edits in either window, it is closer to the listing's own effect at fixed ad bids. Whether
|
|
570
|
+
18. **P-paid-keywords-18.** effect-review's verdict says which effect it measured. Under dynamic or rule-based bidding it is the change's total effect, ads' automatic response included. Under fixed bids (`MANUAL`) with no manual ad edits in either window, it is closer to the listing's own effect at fixed ad bids. Whether bids were held fixed during a window is recorded in the change log. (Sponsored Products 3.0 OpenAPI `MANUAL` definition; Guide to dynamic bidding - up and down, "limit your changes while testing strategies"; Cinelli, Forney & Pearl)
|
|
571
571
|
19. **P-paid-keywords-19.** cx does not read a rise in a query's SQP impressions or the brand's impression share as an organic-rank gain unless the same query's ad impressions for the same reporting week (the week bounds the SQP report schema sets) are known. Amazon includes Sponsored Products in SQP. Even then the two are set side by side as an estimate, because Amazon advises against comparing SQP's metrics with advertising dashboards' figures of the same name. (Search Query Performance dashboard help page; sellingPartnerSearchQueryPerformanceReport schema)
|
|
572
572
|
20. **P-paid-keywords-20.** listing-review may use an auto campaign's close-match and loose-match search terms, and Amazon's keyword recommendations for the seller's ASIN, as Amazon's own reading of what the product is. It labels them as built from "previous shopping queries and your product information", not from the listing text alone. (A guide to targeting with Sponsored Products; Sponsored Products keyword recommendations; Sponsored Products 3.0 OpenAPI)
|
|
573
573
|
21. **P-paid-keywords-21.** Search terms the seller negates as irrelevant may support a listing-review hypothesis that some listing text or attribute signals the wrong use, but they never settle it. Amazon's stated use of such terms is negatives, judged after the click threshold in Amazon's guide, and no Amazon page treats them as evidence about the listing. (A guide to targeting with Sponsored Products; Search term reports in bulksheets; ClearAds Agency; SellerApp)
|
|
@@ -723,7 +723,7 @@ All read 2026-10-14. Seller Central help pages were read through the help hub's
|
|
|
723
723
|
3. **CPT in notifications.** Do `PRICING_HEALTH` / `ANY_OFFER_CHANGED` still carry `competitivePriceThreshold` outside JP after the September 30, 2025 removal from `getCompetitiveSummary`? The notification page and the Seller Central Pricing Health page still name it. *Settles:* a live notification payload, which needs a queue destination; not available today.
|
|
724
724
|
4. **List Price windows.** Is the List Price validation window 90 days (Seller Central page) or 90/180 days by seasonality (customer page)? The April 2026 News post says only "recently". *Settles:* Amazon's pages disagree; ask Selling Partner Support or watch a seasonal ASIN.
|
|
725
725
|
5. **Coupon star floor.** Is the minimum for 1–4 reviews 2.5 (eligibility page, GJHCPEFJ5JJQD52D v14, captured) or 1 (errors page, GLBL4T5C9UAB9T5P, not captured)? Amazon's two pages disagree; neither is preferred here. *Settles:* the coupon dashboard's own error on a real low-rated ASIN, which is also the binding value at run time.
|
|
726
|
-
6. **Does VALIDATION_PREVIEW return `100708` for a price unchanged from the live one?** If so, it is a cheap "am I featurable at this price" probe for a handful of SKUs. *Settles:* one preview on the seller's SKU
|
|
726
|
+
6. **Does VALIDATION_PREVIEW return `100708` for a price unchanged from the live one?** If so, it is a cheap "am I featurable at this price" probe for a handful of SKUs. *Settles:* one preview on the seller's SKU, which persists nothing (P-listing-writes-5).
|
|
727
727
|
7. **Size of the effects.** What is the click-through or conversion effect of a coupon badge or strike-through on Amazon? No Amazon page read gives a figure, and practitioner figures are unsourced. *Settles:* the seller's own `GET_COUPON_PERFORMANCE_REPORT` and SQP click share across a coupon on/off window, judged by effect-review. Not a number for a skill.
|
|
728
728
|
8. **Seller Forums News.** The verifier read five News posts (featured-offer eligibility, reference pricing 2026, coupon pricing 2024, deal/coupon fees 2025, holiday 2026 fees); none shows an absolute posting date, only "N months ago". Still unread: any News post on Prime Exclusive price discounts, on strike-through changes before 2026, and the regional (EU/UK/JP) versions of the eligibility rollout. *Settles:* the forum's News index opened per marketplace.
|
|
729
729
|
9. **Keepa coverage.** Does Keepa's `promotions[]` ("Only Amazon US promotions by Amazon (not 3rd party)") miss third-party Prime-exclusive discounts? Is `buyBoxIsPrimeExclusive` or `deals[]` the better witness? *Settles:* a Keepa read of an ASIN known to run a seller's Prime-exclusive price discount.
|
|
@@ -346,7 +346,7 @@ Seller Central help pages below were read through the help hub's content call (`
|
|
|
346
346
|
| The ASIN's browse node; category review and return topics | Customer Feedback API | `getItemBrowseNode`, then `getBrowseNodeReviewTopics`, `getBrowseNodeReviewTrends`, `getBrowseNodeReturnTopics`, `getBrowseNodeReturnTrends` |
|
|
347
347
|
| FBA return reasons and customer comments per order | Reports API | door.md's FBA returns report; `createReport`, `getReport`, `getReportDocument` |
|
|
348
348
|
| Seller-fulfilled return reason codes | Reports API | door.md's returns-by-return-date report; same operations |
|
|
349
|
-
| Whether a review request can be sent for an order | Solicitations API | `getSolicitationActionsForOrder`; only then `createProductReviewAndSellerFeedbackSolicitation
|
|
349
|
+
| Whether a review request can be sent for an order | Solicitations API | `getSolicitationActionsForOrder`; only then `createProductReviewAndSellerFeedbackSolicitation` |
|
|
350
350
|
| Competitor rating and count history | Keepa | `cx get amazon/us/<ASIN>/product --source keepa` (the box's typed request already sets `rating=1`): `csv[16]` (rating, tenths) and `csv[17]` (non-variation-specific; "rating count" on Keepa's API page, "review count" in Product.java, checked once against Data Kiosk `totalRatingCount` for an own ASIN, Open question 4); the `reviews` object (`ratingCount` / `reviewCount`, variation-specific, `ratingCount` frozen since 2025-04-09 per Keepa) when present in the landed file |
|
|
351
351
|
| Whether any listing write touches review content | n/a | None found. No listing attribute read in this angle writes reviews; review content is not part of a `patchListingsItem` body. [seat: not checked against a product-type schema] |
|
|
352
352
|
| NCX / CX Health, Customer Review Insights UI, Vine status, Q&A | Seller Central only | No API found. The seller exports or pastes into the tree. |
|
|
@@ -510,7 +510,7 @@ Seller Central help pages below were read through the help hub's content call (`
|
|
|
510
510
|
- **P-reviews-and-qa-9**: cx checks whether a variation-family change in Amazon's review sharing landed inside the window: Amazon's notice email, or a step change in the child's rating count with no edit. When one did, the verdict on that window is "cannot tell". (Changes to review sharing across product variations starting Feb 12)
|
|
511
511
|
- **P-reviews-and-qa-10**: A sudden jump or later drop in a competitor's review count is noted as possibly manipulation or deletion. It is not read as the competitor's demand. (The Market for Fake Reviews; How Amazon is using AI to ensure authentic customer reviews)
|
|
512
512
|
- **P-reviews-and-qa-11**: cx never drafts, proposes or sends anything that offers value for a review, asks for a positive review, asks for a review to be changed or removed, routes unhappy buyers away from reviews, or uses variation grouping to pool reviews. (Community Guidelines; Customer Reviews tool | Sell on Amazon; Customer Product Reviews Policies repost)
|
|
513
|
-
- **P-reviews-and-qa-12**: The only review requests cx makes are Amazon's own solicitation: after `getSolicitationActionsForOrder` shows it available, within the per-order limit solicitations.json states and inside the window the setup page states
|
|
513
|
+
- **P-reviews-and-qa-12**: The only review requests cx makes are Amazon's own solicitation: after `getSolicitationActionsForOrder` shows it available, within the per-order limit solicitations.json states and inside the window the setup page states. Vine is something cx may suggest, not do. (solicitations.json; Set up the Solicitations API; Get customer reviews with Amazon Vine)
|
|
514
514
|
- **P-reviews-and-qa-13**: cx does not propose contacting a buyer about a critical review. Amazon staff state that this route was removed, and a seller may only answer a buyer who writes first. (Amazon Removed "Contact Customer" for Critical Reviews?; Please Reconsider the Removal…)
|
|
515
515
|
- **P-reviews-and-qa-14**: cx does not estimate a displayed star rating from star counts, because Amazon's rating is a machine-learned figure. It reads `displayRating` or Keepa's rating history. (Get 4-star ratings… Customer Review Insights; analytics_sellerAnalytics_2025_03_31.graphql)
|
|
516
516
|
- **P-reviews-and-qa-15**: When a seller asks about shopper questions or "what the AI says", cx explains: Amazon said its assistant (Rufus) answered from listing details, reviews and community Q&A; it was renamed Alexa for Shopping on May 13, 2026, and Amazon's page for the new name does not restate the inputs; no API reads or answers Q&A; Q&A material reaches cx only as files the seller puts in the tree. (Amazon's Rufus AI assistant now available to all US customers; 'Amazon Rufus' AI experience comes to the Amazon Shopping app; Alexa for Shopping; selling-partner-api-models tree)
|
|
@@ -10,7 +10,7 @@ Read 2026-10-14 by the research seat. Tags: [official] Amazon's own page or docu
|
|
|
10
10
|
- `effect-review` (mainly): which windows are clean; what counts as "a major sale"; how to get the event dates at run time rather than from memory; what to read so the seller's own and the competitors' promotions are named as confounders; when the honest verdict is "cannot tell".
|
|
11
11
|
- `listing-review`: the trigger family "demand change: seasonal rise and fall; before and after a major sale". A drop in sessions entering an off-season, or the week after an event, is not a listing defect until it has been checked against query volume and the seller's own history for the same weeks.
|
|
12
12
|
- `listing-change-log`: each change record carries the event context of its two windows. That covers which announced events overlap, which of the seller's own promotions ran (with their ids) and which competitor deals were seen.
|
|
13
|
-
- `/listing-watch` (the standing-instruction template): what cx does
|
|
13
|
+
- `/listing-watch` (the standing-instruction template): what cx does when it writes while an event window is open.
|
|
14
14
|
- The report script: the read operations that date events and promotions (Sales `getOrderMetrics`, the promotion and coupon performance reports, Promotions API `searchPromotions`, Data Kiosk promotion fields).
|
|
15
15
|
|
|
16
16
|
**Why a senior operator cares.** Event weeks are the largest movements most listings ever see, and their dates move from year to year. Prime Day ran in July 2025 over four days and in June 2026 over four days. Prime Big Deal Days ran on 7–8 October 2025 and 6–7 October 2026. A seller's 30-day baseline pulled on 2026-10-13 already contains Prime Big Deal Days 2026. That is what day 1 of the beta run pulled: `GET_SALES_AND_TRAFFIC_REPORT` for 2026-09-13 to 2026-10-13. The day-2 proposal then put a 10% coupon (row 8) into one package of 13 changes, six of them text attributes, beside images, A+ and ads, and named no event (`office-mailbox/from-engineering/20261013-0904-…day-1.md`, item 2; `…20261014-0921-…day-2.md`, item D and the proposal quoted whole). An operator reads every number through the calendar first. cx did not.
|
|
@@ -491,7 +491,7 @@ Note on method: the session's web-search budget ran out after one search. Every
|
|
|
491
491
|
11. **P-seasonality-and-events-11**: cx states deal-eligibility thresholds and event submission deadlines only from Amazon's page, naming the page and the version recorded in the tree, or from the seller's Seller Central copy; never from memory. A rating drop or a missed deadline is a reason a planned event deal may not run. — Guide to running Amazon seller promotions…; Prime Day | Sell on Amazon.
|
|
492
492
|
12. **P-seasonality-and-events-12**: cx does not assume a post-event halo or a post-event dip. It reads the seller's own daily orders around the last events and lets that shape set how long the after-event exclusion lasts for that ASIN. — The impact of peak events… (Perpetua); Amazon Prime Day 2025 Is Official… (Seller Labs); Amazon Lightning Deals: Everything You Need to Know (eComEngine); SPADE.
|
|
493
493
|
13. **P-seasonality-and-events-13**: A returns-targeted verdict whose window includes holiday purchases waits until Amazon's extended return date has passed and Amazon's return data has caught up. — Amazon's holiday return policy 2025; Seller Analytics Dataset Use Case Guide.
|
|
494
|
-
14. **P-seasonality-and-events-14**: When
|
|
494
|
+
14. **P-seasonality-and-events-14**: When cx writes while an event window is open, cx's report says the change's effect cannot be judged until the window clears, and the change log records the event beside the change. — Controlled experiments on the web (Kohavi et al. 2009); SPADE.
|
|
495
495
|
|
|
496
496
|
15. **P-seasonality-and-events-15**: cx proposes a listing change before an event only when the change can be live and its whole observation window can close before the event's early-deals run-up begins. For planning it allows the propagation time Amazon states on its search glossary page at the time, which Amazon says can be slower at high traffic; the window itself opens only on the date cx reads the change back as live. Otherwise it proposes the change for after the event's ramp-down. — Amazon search glossary; Product title requirements and guidelines; Controlled experiments on the web (Kohavi et al. 2009); SPADE.
|
|
497
497
|
16. **P-seasonality-and-events-16**: For an A+ change cx adds Amazon's stated review and publishing time, read from Amazon's current A+ guide ("longer during periods of high volume", and the review again after a rejection), before the observation window. It does not submit A+ where that time could land the publish inside an event window. — Complete Guide to A+ Content for Brand Owners; A+ moderation — rejection reasons… (AMALYZE, as practitioner support).
|
|
@@ -340,7 +340,7 @@ Help pages below were read through the content call, layer `Published/US`, local
|
|
|
340
340
|
|
|
341
341
|
1. **The description's length limit and HTML rule.** No Amazon page read states the length limit (Error code explanations, G17781, gives 1000 characters only as an example of an error class). The written HTML rule is on Product detail page rules (G200390640 v21: no code, line breaks allowed in the description); what is open is how the listing pipeline treats a tag in `product_description` for a given product type. Settle by the first real run: `getDefinitionsProductType` for the seller's product type (the beta run's `<PRODUCT_TYPE>`) in the US store; read `properties.product_description` for `maxLength`/`maxUtf8ByteLength` and any pattern. Then a `VALIDATION_PREVIEW` patch with a `<br>` and one with `<p>`, to see whether 90199 fires on this attribute.
|
|
342
342
|
2. **Amazon's written content rules for the description** (prohibited claims, HTML, line breaks). *Settled for the help pages:* G200390640 is "Product detail page rules" and G202024200 is "Misleading and prohibited claims", both read on 2026-10-14 through the content call (captures capture `G200390640-v21` and G202024200-v11.txt; G1, G2), and the line-break exception is on the rules page itself. (The first pass called both pages behind sign-in; a plain fetch returns only a JavaScript shell, and the content call needs no sign-in.) Still open: the category style guides. The rules page's link to them now lands on "Bulk listing templates", which links none. Settle by finding the current style-guide page from a signed-in Seller Central session or Seller Assistant, and by reading the product type's schema `description` text for `product_description`.
|
|
343
|
-
3. **Is a description hidden by A+ still indexed, and still used by Alexa for Shopping?** No Amazon statement was found; practitioners disagree. Settle only through an Amazon statement, or a controlled test
|
|
343
|
+
3. **Is a description hidden by A+ still indexed, and still used by Alexa for Shopping?** No Amazon statement was found; practitioners disagree. Settle only through an Amazon statement, or a controlled test on a live ASIN, which changes that ASIN's description while it runs (a unique token placed only in the hidden description, then searched for). The seat does not recommend running that test on a live hero ASIN. *Gap fill:* half narrowed. Amazon does state that the description in general is matched by keyword search (G10471, G1661). It still says nothing about a description hidden by A+, or about Alexa for Shopping reading it. The pages that might say so (the A+ help pages in Seller Central, an Alexa for Shopping seller page) were not found in this session; the web-search budget ran out before a search for them.
|
|
344
344
|
4. **Settled by the gap fill:** the 2026 quick guide says Basic A+ "is located under 'Product description' on listings", and the 2023 US guide says the modules "populate the 'Product Description' section" (G4). The original question was: **Does Basic (Standard) `EBC` A+ fill the same slot as Premium?** Amazon's developer-page sentence is about Premium; Manny_Amazon's staff post says A+ in general "replaces the plain-text product description in the Product Description section". Largely settled at forum-staff level; a screenshot of a detail page with Basic A+, or the A+ help page (sign-in), would settle it at page level.
|
|
345
345
|
5. **Does `searchContentPublishRecords` return only live content?** Does it include suspended or rejected content? The model calls them "publishing records" and says no more. Settle by a first real read on an ASIN with known A+ status, compared with the detail page.
|
|
346
346
|
6. **Who can read A+ for the beta seller.** The door's granted roles (Brand Analytics or Product Listing) and whether the seller is a brand owner. This is door.md's, settled by the first `searchContentPublishRecords` call.
|
|
@@ -361,7 +361,7 @@ Help pages below were read through the content call, layer `Published/US`, local
|
|
|
361
361
|
- **P-description-3.** Before proposing or judging any description change, check `searchContentPublishRecords` for the ASIN. If seller A+ (`EBC`) is published, record that the plain description does not occupy the detail page's Product Description slot and is not the conversion element there. Sources: A+ Premium Modules; aplusContent_2020-11-01.json; Seller Forums posts by Michelle_Amazon ("A+ Content replaces your product description") and Manny_Amazon ("it replaces the plain-text product description in the Product Description section"); (reconciliation) A+ Content help page G202102930 ("will hide the current plain-text product description"), as quoted in elements/a-plus-content.md.
|
|
362
362
|
- **P-description-4.** Where vendor A+ (`EMC`, or Keepa `aPlus[].fromManufacturer` true) is present, treat it as sitting under "From the Manufacturer", not as proof the plain description is hidden. Record that Amazon says retail-vendor A+ in most cases appears in place of seller A+ and that the seller cannot add or edit A+ on such an ASIN. Sources: A+ Premium Modules; Keepa Product Object; A+ Content (G202102930, as quoted in elements/a-plus-content.md).
|
|
363
363
|
- **P-description-5.** Put no HTML in a proposed description unless a `VALIDATION_PREVIEW` of that exact text returns no issue; issue 90199 is Amazon's refusal of HTML tags, and Amazon has announced that HTML tags on detail pages are unsupported and may cost the line. Sources: Listings Items API Issues Troubleshooting; Manage Listings Issues; Seller Forums News post by News_Amazon ("Detail pages will not show HTML formatting on your listing information"); Seller Forums post by Jessica_Amazon_.
|
|
364
|
-
- **P-description-6.** Every description write goes preview first: `patchListingsItem` with `mode=VALIDATION_PREVIEW`,
|
|
364
|
+
- **P-description-6.** Every description write goes preview first: `patchListingsItem` with `mode=VALIDATION_PREVIEW`, which persists nothing, then the write. Success is read afterwards as `issues` empty and the Catalog value equal to the submitted text. Sources: Manage Listings Issues; listing-searchability SKILL.md (Amazon selling-partner-agentic-toolkit); Listings APIs FAQ.
|
|
365
365
|
- **P-description-7.** A description patch replaces the whole value, so the change log records the full before and after text, not a fragment. The `merge` operation does not apply to `product_description`. Sources: Preview errors before partially updating a listing; Listings Items API; listingsItems_2021-08-01.json.
|
|
366
366
|
- **P-description-8.** The change log for a description change records whether `EBC` A+ was published on the ASIN at write time and at the end of the observation window. Sources: A+ Premium Modules; aplusContent_2020-11-01.json.
|
|
367
367
|
- **P-description-9.** In an effect review, an A+ publish, edit or suspension inside the baseline or observation window is a confounder for any description change, because it changes what fills the same slot. Sources: A+ Premium Modules; aplusContent_2020-11-01.json.
|
|
@@ -509,7 +509,7 @@ The session's web-search budget ran out partway through the research. Pages not
|
|
|
509
509
|
- First proposed settlement: the seller (or Jack, signed in) opens G23501 and "Keyword attributes explained" and pastes the text. SellerSprite also cites a "G201047930" page under that name.
|
|
510
510
|
- **Gap fill 2026-10-14: settled.** The live US page (G23501 v14) states no figure, says spaces and punctuation are not counted, and has no over-limit FAQ; the live "Keyword attributes explained" (v4) gives 249 and "completely ignored"; G10471 (v13) gives "less than 250 bytes". G201047930 serves no topic. Every other marketplace's live page states its own figure (§F1–F3).
|
|
511
511
|
2. **Is a value longer than the stated indexing limit, but accepted by the schema (500–2000 bytes), indexed at all? In part? Or does it make the whole field ignored?** No Amazon page read today answers this. Staff replies keep saying 249.
|
|
512
|
-
- Settle it: Amazon's current help page. Failing that, a deliberate test on a seller's low-stakes ASIN,
|
|
512
|
+
- Settle it: Amazon's current help page. Failing that, a deliberate test on a seller's low-stakes ASIN, which while it runs changes data hidden from shoppers and the ASIN's search eligibility, with indexing not guaranteed: two values, one term only in the tail, then SQP impressions for that term.
|
|
513
513
|
3. **With several `generic_keyword` values per marketplace (the "five boxes"), does the indexing limit apply per value or to their total?**
|
|
514
514
|
- Settle it: the current help page. The first real `getListingsItem` read shows whether sellers' listings carry several values.
|
|
515
515
|
4. **What are `maxUtf8ByteLength` and `maxLength` for `generic_keyword` in current US schemas?** Do US schemas still carry `target_audience_keyword`, `subject_keyword`, `specific_uses_keyword` or `thesaurus_subject_keyword`?
|
|
@@ -552,7 +552,7 @@ All help pages in this section were read through the help hub content call (laye
|
|
|
552
552
|
|
|
553
553
|
## Open questions
|
|
554
554
|
|
|
555
|
-
1. **Does a `patchListingsItem` `delete` on `child_parent_sku_relationship` unlink a child without deleting it?** Amazon's guide documents only listing deletion, while practitioners clear the parent fields in flat files. *Settle:* a `VALIDATION_PREVIEW` on a sandbox or a
|
|
555
|
+
1. **Does a `patchListingsItem` `delete` on `child_parent_sku_relationship` unlink a child without deleting it?** Amazon's guide documents only listing deletion, while practitioners clear the parent fields in flat files. *Settle:* a `VALIDATION_PREVIEW` on a sandbox or a live SKU (a preview persists nothing), then Catalog `relationships` after processing.
|
|
556
556
|
2. **Does a re-linked child keep its own reviews and sales history?** Does a new parent ASIN reset parent-level history? *Gap fill: partly.* G201951410 says "Existing ASINs may already have sales history and reviews … Using existing ASINs preserves this history". That is about the child ASIN, not the parent's series. G8841 is not served. *Settle:* the first real family change observed in Catalog and Data Kiosk.
|
|
557
557
|
3. **What exactly do the review sharing guidelines (G74DLBUEHT5GY88C) say?** That covers the full list of non-sharing themes, "inconsistent use", and appeals. *Gap fill: settled for the list and appeals* (H10, and the flavour note above). The page states no appeal. The guideline page does not use the word "inconsistent"; the whole-family rule ("being inconsistently used and include significant differences") is stated only in the News_Amazon threads quoted above.
|
|
558
558
|
4. **Is there an API answer for review-sharing eligibility?** Seller Assistant is the only channel found. *Settle:* SP-API release notes after 2026-10 and the Data Kiosk seller analytics docs.
|
|
@@ -562,7 +562,7 @@ All help pages in this section were read through the help hub content call (laye
|
|
|
562
562
|
8. **Which `issues` codes signal a variation problem** (theme attribute missing, parent buyable, deprecated theme)? *Settle:* the first real `getListingsItem` on a parent and child.
|
|
563
563
|
9. **Can Amazon Ads advertise a parent ASIN?** How do ads attribute across children? *Gap fill: partly settled.* Sibling purchases are other-SKU sales of the advertised SKU (H9). A parent has the eligibility status `VARIATION_PARENT`, but the model does not say whether its severity is `INELIGIBLE` or `ELIGIBLE_WITH_WARNING`. *Settle:* one `POST /eligibility/product/list` on a parent ASIN once the Ads API is connected.
|
|
564
564
|
10. **The original theme-removal announcement and the spreadsheet of removed themes.** *Reconciliation: partly settled.* The first forum post (2025-08-19) was read: the 2025-09-02 to 2025-11-30 window, "Deprecated: Do Not Use", the "the value specified is invalid" error and the rebuild steps are Amazon's (angles/competitor-discovery.md had them right). *Still open:* the Seller News article it points to, the "Variation themes planned for removal" spreadsheet, and whether the error applies to themes kept after the revision. *Settle:* Seller Central signed in for the article and spreadsheet; `getDefinitionsProductType` `enumDeprecated` for the live values.
|
|
565
|
-
11. **Theme change: allowed or not?** The help pages say a theme cannot be changed. The 2025 and 2026 announcements and an older moderator speak of updating themes (H1). The 2025 first post's "update" is the rebuild under a new parent; whether an in-place replace through the API is accepted is still open. *Settle:* a `VALIDATION_PREVIEW` `patchListingsItem` that replaces `variation_theme` on a
|
|
565
|
+
11. **Theme change: allowed or not?** The help pages say a theme cannot be changed. The 2025 and 2026 announcements and an older moderator speak of updating themes (H1). The 2025 first post's "update" is the rebuild under a new parent; whether an in-place replace through the API is accepted is still open. *Settle:* a `VALIDATION_PREVIEW` `patchListingsItem` that replaces `variation_theme` on a sandbox or a live parent (a preview persists nothing), and the `issues` it returns.
|
|
566
566
|
12. **Is the Variation Wizard still live?** Its help page is gone in seven layers, while Amazon's blogs (2024-12 and 2026-04) still send sellers to it. *Settle:* the seller opening `/listing/varwiz`, or Catalog > Add Products, on the first run.
|
|
567
567
|
13. **Do the SP-API listings reports (`GET_MERCHANT_LISTINGS_ALL_DATA`, `GET_MERCHANT_LISTINGS_DATA`) carry a parent ASIN or parentage column?** The Seller Central FAQ says the Active and All Listings reports hold "Parent ASIN details". The SP-API page describes no such column. *Settle:* the first downloaded report (door.md's operation names).
|
|
568
568
|
14. **Does a merge or re-parenting move a child's "bought in past month" badge or Keepa `monthlySold`?** Amazon's only word is "unique customers who purchased the ASIN in the past 30 days" (moderator), and Keepa says the value is variation specific. Nothing covers merges. *Settle:* Keepa `monthlySoldHistory` across a recorded family change.
|
|
@@ -576,7 +576,7 @@ All help pages in this section were read through the help hub content call (laye
|
|
|
576
576
|
|
|
577
577
|
1. **P-variations-1:** Before proposing any family change, cx reads the seller's side (`getListingsItem` `relationships` and `searchListingsItems` `variationParentSku`) and Amazon's side (Catalog `relationships`) and records the whole family in the change log's "before". Sources: Building Listings Management Workflows Guide; listingsItems_2021-08-01.json; catalogItems_2022-04-01.json.
|
|
578
578
|
2. **P-variations-2:** cx takes the allowed themes and each theme's required attributes from `getDefinitionsProductType` at the listing's `parentageLevel`, never from memory, and never proposes a value flagged `enumDeprecated`. Sources: Building Listings Management Workflows Guide; definitionsProductTypes_2020-09-01.json; Update to irrelevant or redundant variation theme removal.
|
|
579
|
-
3. **P-variations-3:** cx treats deleting a parent, deleting a child, moving a child to another parent, and changing a theme as high-risk changes, because the documented removal path deletes listings and a parent's deletion unlinks every child. Each one names its reversal path
|
|
579
|
+
3. **P-variations-3:** cx treats deleting a parent, deleting a child, moving a child to another parent, and changing a theme as high-risk changes, because the documented removal path deletes listings and a parent's deletion unlinks every child. Each one names its reversal path. Sources: Building Listings Management Workflows Guide.
|
|
580
580
|
4. **P-variations-4:** cx flags any child that differs in function, generation or model from its siblings as a policy risk. It proposes a separate detail page, not a better theme. Sources: How to create Amazon product variations; Changes to review sharing across product variations starting from Feb 12.
|
|
581
581
|
5. **P-variations-5:** cx never proposes adding a product to a family in order to borrow reviews, rating or rank. If it sees a competitor doing so, it reports it as a possible abuse case for the Report abuse page, not as a tactic. Sources: FTC Charges Supplement Marketer with Hijacking Ratings and Reviews on Amazon.com…; FTC Approves Final Order against The Bountiful Company; Variation abuse and review manipulation by Seller; How to create Amazon product variations (functionally different products listed separately).
|
|
582
582
|
6. **P-variations-6:** When a child's displayed rating or review count drops with no new reviews, cx's first hypothesis is the 2026 review-sharing rule applied to the family's theme. It checks the theme against Amazon's sharing types and asks the seller to confirm eligibility in Seller Assistant. Sources: Changes to review sharing…; Check review sharing eligibility with Seller Assistant.
|
|
@@ -910,7 +910,7 @@ Internal, read for what the run did (not cited as Amazon):
|
|
|
910
910
|
- **P-listing-writes-13.** For titles in non-media product types, cx proposes `item_name` within the schema's limit plus `title_differentiation`. It warns that a longer `item_name` is accepted but may be reconciled, split, or replaced by an AI recommendation. Sources: Submit modular titles; Seller Forums "Updates to improve your product titles begin on July 27".
|
|
911
911
|
- **P-listing-writes-14.** cx does not resend unchanged data. Amazon says duplicate submissions lengthen processing. Sources: Building Listings Management Workflows Guide.
|
|
912
912
|
- **P-listing-writes-15.** A product type schema cx has fetched may be reused, but is re-fetched when the product type definitions change. Sources: Building Listings Management Workflows Guide (the caching note under step 3); Notification Type Values; definitionsProductTypes_2020-09-01.json (`checksum`).
|
|
913
|
-
- **P-listing-writes-16.** cx proposes a delete only as an irreversible change, never as a cheap way to fix a listing.
|
|
913
|
+
- **P-listing-writes-16.** cx proposes a delete only as an irreversible change, never as a cheap way to fix a listing. When cx proposes one, it says what the delete takes with it:
|
|
914
914
|
- the offer in that store;
|
|
915
915
|
- the item's relationships (all children's, for a parent);
|
|
916
916
|
- the FBA link, if a re-created listing does not have the same SKU and ASIN;
|
|
@@ -462,7 +462,7 @@ Practitioners disagree with Amazon on one point that matters here. The documenta
|
|
|
462
462
|
- **P-report-lifecycle-8.** For a Brand Analytics report, cx sends exactly one period per request, from the period's first day to its last (Sunday to Saturday for `WEEK`). A longer window is several reports, said to the seller before any is created. (Analytics Reports)
|
|
463
463
|
- **P-report-lifecycle-9.** For Sales and Traffic at `WEEK` or `MONTH`, cx records the expanded range Amazon will use, not the range it typed, and marks a period that ends in the future as partial. (Analytics Reports)
|
|
464
464
|
- **P-report-lifecycle-10.** On a 429, cx stops, tells the seller, and waits with back-off before one retry. It never loops `createReport`, and it treats the `x-amzn-RateLimit-Limit` value as the plan in force. (Usage Plans and Rate Limits; Optimize Rate Limits for Application Workloads; Analytics Reports)
|
|
465
|
-
- **P-report-lifecycle-11.** cx
|
|
465
|
+
- **P-report-lifecycle-11.** cx reads `getReportSchedules` for that type before it creates or replaces a report schedule. A new schedule silently replaces any existing schedule for the same type and stores. (reports_2021-06-30.json; Schedule and retrieve reports)
|
|
466
466
|
- **P-report-lifecycle-12.** cx cancels only its own report and only while it is `IN_QUEUE`, and a Data Kiosk query only while it is `IN_QUEUE` or `IN_PROGRESS`. (reports_2021-06-30.json; dataKiosk_2023-11-15.json)
|
|
467
467
|
- **P-report-lifecycle-13.** For Data Kiosk, cx reads `getQuery` to a terminal status. It reads `dataDocumentId` as data, `errorDocumentId` as Amazon's explanation, and `DONE` with neither as "no data for that range". (Verify that query processing is complete; Data Kiosk API)
|
|
468
468
|
- **P-report-lifecycle-14.** cx counts a Data Kiosk result as complete only when the query carries no `pagination.nextToken`. Otherwise it issues a new `createQuery` with the same `query` and that token per page, and tells the seller how many pages the figure rests on. (dataKiosk_2023-11-15.json; Data Kiosk Query Processing Finished Notification)
|
|
@@ -481,7 +481,7 @@ Practitioners disagree with Amazon on one point that matters here. The documenta
|
|
|
481
481
|
|
|
482
482
|
### The seat's own (not for a skill)
|
|
483
483
|
|
|
484
|
-
- S1. Report-type limits appear to be metered per seller account and shared with the seller's other applications and Seller Central. A 429 or `FATAL` on a report may therefore be caused by another tool,
|
|
484
|
+
- S1. Report-type limits appear to be metered per seller account and shared with the seller's other applications and Seller Central. A 429 or `FATAL` on a report may therefore be caused by another tool, and a schedule cx creates draws on the limits the seller's other tools share. This rests only on support texts relayed by developers (GitHub #5210) and an internal run that saw reports it did not create.
|
|
485
485
|
- S2. Options are validated only when processing starts, so a wrong option costs a queue slot as well as a create token. This rests on Amazon's replies in internal runs, not on a page.
|
|
486
486
|
- S3. SQP reports for one seller appear to be processed one at a time, each taking tens of minutes. A playbook should therefore treat SQP as a background job, collected on a later turn, and never as a wait inside one chat turn. This rests on the internal research run and on practitioner reports (#5240, Openbridge).
|
|
487
487
|
- S4. Two date forms of one Brand Analytics period (date-only and date-time) gave the same document in an internal run, and the record keeps a date-only `dataEndTime` as midnight at the start of that day. Sending the date-time form ending `T23:59:59Z` keeps the stored end at the period's end. Not stated by Amazon.
|
|
@@ -15,7 +15,7 @@ Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers
|
|
|
15
15
|
- **After.** The submitted values, which `getListingsItem` returns, and the later Catalog view, which reconciliation, title splitting or another contributor's precedence can change (P-listing-writes-7). A differing Catalog value, or an Amazon change during the window, makes the verdict cannot tell (P-effect-measurement-8).
|
|
16
16
|
- **Expected.** Fixed before the write: the targeted stage, metric and orders with their sources, the expected direction and range, the smallest move that counts, both windows by date, the dated control set, and the expected lag and shape (P-effect-measurement-6). A later edit to these carries its reason (P-effect-measurement-6).
|
|
17
17
|
- **Words bet on.** Search Query Performance queries as Amazon spells them, with the ASIN's share at each stage over the baseline weeks (P-search-query-performance-9). Each notes whether it had paid search-term rows at baseline, compared in the observation window (P-paid-keywords-7).
|
|
18
|
-
- **Decisions.** The seller's
|
|
18
|
+
- **Decisions.** The seller's words on the change, where the seller gave any, and whether bids are held fixed (P-paid-keywords-18). The cannot-tell outcome (keep, revert, extend once, or Manage Your Experiments) is written before the change (P-effect-measurement-39).
|
|
19
19
|
- **Request and receipt.** The operation as the request it would be sent: origin, method, path and body; then Amazon's `submissionId`, `status` and `issues` (P-listing-writes-8). `ACCEPTED` means accepted for processing, not done (P-listing-writes-6). Amazon raises issues asynchronously after acceptance (P-listing-policies-13).
|
|
20
20
|
- **Window dates.** The observation window opens when `getListingsItem` holds the new value with no `ERROR` issue and `getCatalogItem` then shows it (P-effect-measurement-7). An exposure or click-through reading starts at the first whole report week after Amazon's stated search latency, quoted from its page into the file (P-effect-measurement-7). Each kind of change has its own go-live window on its help page, an allowance before exposure is read and not proof the change is live (P-funnel-and-search-15). A+ and Brand Story windows open at confirmed publication (P-a-plus-content-6; P-brand-story-and-store-5). The window's end is set here (P-effect-measurement-11).
|
|
21
21
|
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
|
|
71
71
|
- The baseline holds the bidding strategy, placement adjustments and bid or budget rules of every campaign advertising the changed SKU (P-paid-keywords-16).
|
|
72
72
|
- Under dynamic or rule-based bidding the measured effect includes the ads' automatic response; under `MANUAL` bids with no ad edits in either window it is closer to the listing's own effect (P-paid-keywords-18).
|
|
73
|
-
- Whether bids are held fixed during a window
|
|
73
|
+
- Whether bids are held fixed during a window changes which effect is measured, and the record holds it (P-paid-keywords-18).
|
|
74
74
|
- Sponsored Products creative shows the title and automatic targeting draws on product information, so ad impressions and click-through are part of a title change's effect on an advertised ASIN (P-title-27).
|
|
75
75
|
|
|
76
76
|
## Families and deletes
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
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
|
|
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, 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
4
|
---
|
|
5
5
|
|
|
6
6
|
Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
|
|
@@ -36,7 +36,7 @@ Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers
|
|
|
36
36
|
|
|
37
37
|
## Preview and write
|
|
38
38
|
|
|
39
|
-
- 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
|
|
39
|
+
- 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 is the write: a real submission, which Amazon validates and processes and may answer `INVALID`, and which on a SKU that exists replaces the content and drops what it omits (P-listing-writes-5; P-listing-create-17; P-listing-create-18; P-listing-create-8).
|
|
40
40
|
- A preview answers `VALID` or `INVALID` with `issues` (P-listing-create-17).
|
|
41
41
|
- 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).
|
|
42
42
|
- 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).
|
|
@@ -49,7 +49,7 @@ Each sentence ends with the research item it rests on: P-<file>-<n> is in the pa
|
|
|
49
49
|
## The competitor set
|
|
50
50
|
|
|
51
51
|
- `getCompetitiveSummary` with `includedData` `similarItems` returns Amazon's list of ASINs comparable to an item (P-competitor-set-3).
|
|
52
|
-
- The competitor set is the seller's named rivals plus
|
|
52
|
+
- The competitor set is the seller's named rivals plus Amazon's `similarItems` candidates, and cx confirms what each is before tracking it and says which set it used (P-triggers-15; P-competitor-set-3).
|
|
53
53
|
- A comparison group is chosen on data from before the change and is valid only for units the change did not affect (Brodersen et al.), so a set altered inside an observation window is not that window's comparison, and a re-pick is a new, dated version of the set (P-competitor-set-6).
|
|
54
54
|
- An entrant that arrives on the core terms during a window is a confounder of that window, not a new member of its control (P-competitor-discovery-13).
|
|
55
55
|
- Amazon's Acceptable Use Policy forbids aggregating data across Authorized Users' businesses to provide or sell to any party (4.4) and disclosing it to other application users (4.6), so competitor data from one seller's connection serves only that seller (P-competitor-set-20).
|