cx-listing-playbook 0.2.0 → 0.4.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 +20 -54
- package/README.zh-CN.md +31 -0
- package/package.json +51 -2
- package/prompts/listing-create.md +1 -1
- package/prompts/listing-review.md +1 -1
- package/research/README.md +6 -1
- package/research/method/featured-offer.md +111 -0
- package/research/method/listing-create.md +7 -1
- package/research/method/playbook-defaults.md +34 -0
- package/skills/featured-offer/SKILL.md +45 -0
- package/skills/featured-offer/references/causes.md +30 -0
- package/skills/featured-offer/references/reads.md +33 -0
- package/skills/featured-offer/references/support.md +10 -0
- package/skills/listing-create/SKILL.md +2 -1
- package/skills/listing-create/references/request.md +9 -0
- package/skills/listing-review/SKILL.md +4 -0
- package/skills/listing-review/references/funnel.md +2 -1
- package/prompts/listing-watch.md +0 -7
package/README.md
CHANGED
|
@@ -1,65 +1,31 @@
|
|
|
1
|
-
|
|
1
|
+
This playbook teaches cx how to work on your Amazon listings: creating new ones, seeing how each one is doing and why, proposing changes, and judging afterwards whether a change worked.
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
With it, cx:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- Creates listings in the stores you name, from your own words and your product's data. It shows you what Amazon's own check says first, and writes to your store only after you say yes.
|
|
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, and sends it only after you say yes.
|
|
8
|
+
- Keeps a record of every change: before and after, what was expected, and Amazon's receipt.
|
|
9
|
+
- Tells you, once enough time has passed, whether a change worked, did not, or cannot be told yet.
|
|
10
|
+
- Explains the Buy Box: whether your offer holds it, why not, and which causes you can fix in your store.
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
To have cx keep watching a listing for you, also install cx-listing-watch.
|
|
8
13
|
|
|
9
|
-
|
|
10
|
-
|---|---|
|
|
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
|
-
| `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 |
|
|
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 发货` |
|
|
16
|
-
| `prompts/listing-review.md` | `/listing-review <ASIN>`: the listing and its issues, the market since last time, a proposal with its reasons |
|
|
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,有要改的告诉我,没事别吵` |
|
|
14
|
+
## Try it
|
|
18
15
|
|
|
19
|
-
|
|
16
|
+
- `/listing-create US,DE new product, data in /tenant/products/new-router/, shipped by FBA`
|
|
17
|
+
- `/listing-review <ASIN>`
|
|
20
18
|
|
|
21
|
-
##
|
|
19
|
+
## What it uses
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
| `/tenant/listings/<ASIN>/watch.md` | The standing instruction `/listing-watch` writes |
|
|
26
|
-
| `/tenant/listings/<ASIN>/changes/` | One file per listing change; changes made together are one change |
|
|
27
|
-
| `/tenant/reports/<reportType>/<ask>/<n>/` | One report of that ask: `receipt.json` with the report id, Amazon's status and `createdTime`, each reply as Amazon gave it, and the document |
|
|
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 them only with your yes.
|
|
22
|
+
- **Keepa,** where you have it: price and rank history, and your competitors' listings.
|
|
28
23
|
|
|
29
|
-
|
|
24
|
+
Each is its own plugin, and its page gives its price.
|
|
30
25
|
|
|
31
|
-
|
|
32
|
-
scripts/report.sh <reportType> --origin <origin> --marketplace <id>[,<id>...] [--start <ISO 8601>] [--end <ISO 8601>] \
|
|
33
|
-
[--option <name>=<value>]... --wait <seconds> [--every <seconds>]
|
|
34
|
-
```
|
|
26
|
+
## Where cx keeps things
|
|
35
27
|
|
|
36
|
-
|
|
28
|
+
- One file per change to a listing, in `/tenant/listings/<ASIN>/changes/`.
|
|
29
|
+
- Amazon's reports as they came, in `/tenant/reports/`.
|
|
37
30
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
pi, and in the box the `cx` command with the Amazon SP-API source; Keepa where a skill names a Keepa field. It reaches no network itself except the one document link Amazon hands the script.
|
|
41
|
-
|
|
42
|
-
## Install
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
pi install npm:cx-listing-playbook # for you, in ~/.pi/agent/settings.json
|
|
46
|
-
pi install -l npm:cx-listing-playbook # for one project, in .pi/settings.json
|
|
47
|
-
pi remove npm:cx-listing-playbook
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
On ComChatX, a seller installs it from the Plugins page.
|
|
51
|
-
|
|
52
|
-
## Develop
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
npm ci
|
|
56
|
-
npm run typecheck
|
|
57
|
-
npm test # pi at the pin loads the package and expands every template; every text line cites a research item;
|
|
58
|
-
# the script runs against a stub cx
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
`TENANT_TREE` moves the script's tree from `/tenant` for a run outside the box, as the tests do.
|
|
62
|
-
|
|
63
|
-
## Licence
|
|
64
|
-
|
|
65
|
-
MIT. See [LICENSE](LICENSE).
|
|
31
|
+
Every fact this playbook gives cx names its source; the sources are in [`research/`](research/README.md).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
这套方法教 cx 打理你的亚马逊 listing:创建新 listing,看每条 listing 表现如何、原因是什么,提出修改建议,事后判断修改有没有见效。
|
|
2
|
+
|
|
3
|
+
装上之后,cx 会:
|
|
4
|
+
|
|
5
|
+
- 按你的描述和产品资料,在你指定的站点创建 listing。提交前先给你看亚马逊自己的检查结果,你同意后才写入店铺。
|
|
6
|
+
- 从搜索到下单逐步检查一条 listing,说明它比上次检查时有什么变化,并读取亚马逊对这条 listing 给出的信息。
|
|
7
|
+
- 提出修改建议,附上理由和依据的数据,你同意后才提交。
|
|
8
|
+
- 每次修改都留一份记录:改前改后、预期效果和亚马逊的回执。
|
|
9
|
+
- 等观察期足够后,告诉你这次修改已见效、未见效,还是暂时无法确定。
|
|
10
|
+
- 分析 Buy Box:你的报价有没有拿到、为什么没拿到,以及哪些原因能在店铺里解决。
|
|
11
|
+
|
|
12
|
+
如果想让 cx 持续帮你盯一条 listing,再装上 cx-listing-watch。
|
|
13
|
+
|
|
14
|
+
## 试一试
|
|
15
|
+
|
|
16
|
+
- `/listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货`
|
|
17
|
+
- `/listing-review <ASIN>`
|
|
18
|
+
|
|
19
|
+
## 用到的数据
|
|
20
|
+
|
|
21
|
+
- **Amazon SP-API**:你的亚马逊卖家账户,在 Amazon SP-API 插件里连接。cx 在这里读取你的 listing、报价和报告,只有你同意后才会修改。
|
|
22
|
+
- **Keepa**(如果你装了):价格和排名的历史,以及竞品的 listing。
|
|
23
|
+
|
|
24
|
+
两者各是一个插件,价格见各自的页面。
|
|
25
|
+
|
|
26
|
+
## cx 把东西放在哪
|
|
27
|
+
|
|
28
|
+
- 每次修改一个文件,放在 `/tenant/listings/<ASIN>/changes/`。
|
|
29
|
+
- 亚马逊报告的原件,放在 `/tenant/reports/`。
|
|
30
|
+
|
|
31
|
+
这套方法给 cx 的每条事实都注明出处,出处在 [`research/`](research/README.md)。
|
package/package.json
CHANGED
|
@@ -1,9 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cx-listing-playbook",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.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",
|
|
7
|
+
"comchatx": {
|
|
8
|
+
"about": "让 cx 创建和检查 listing、分析 Buy Box,记录并评估每次修改。",
|
|
9
|
+
"mark": {
|
|
10
|
+
"line": "chart"
|
|
11
|
+
},
|
|
12
|
+
"section": "extensions",
|
|
13
|
+
"order": 50,
|
|
14
|
+
"skills": {
|
|
15
|
+
"listing-create": {
|
|
16
|
+
"about": {
|
|
17
|
+
"en": "Creating a listing in the stores you name, from your product's data.",
|
|
18
|
+
"zh": "用你的产品资料在你指定的站点创建 listing。"
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"listing-review": {
|
|
22
|
+
"about": {
|
|
23
|
+
"en": "How a listing performs and why, and how a change to it is checked before it is sent.",
|
|
24
|
+
"zh": "分析 listing 的表现和原因,提交修改前检查。"
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"listing-change-log": {
|
|
28
|
+
"about": {
|
|
29
|
+
"en": "One file for each change to a listing: before, after, what was expected and Amazon's receipt.",
|
|
30
|
+
"zh": "每次修改 listing 都存一个文件,写明改前改后、预期效果和亚马逊的回执。"
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"effect-review": {
|
|
34
|
+
"about": {
|
|
35
|
+
"en": "Whether a change worked, did not, or cannot be told yet.",
|
|
36
|
+
"zh": "判断一次修改已见效、未见效,还是暂时无法确定。"
|
|
37
|
+
}
|
|
38
|
+
},
|
|
39
|
+
"featured-offer": {
|
|
40
|
+
"about": {
|
|
41
|
+
"en": "How Amazon picks the Featured Offer (Buy Box), why your offer holds it or not, and which causes a change in your store can reach.",
|
|
42
|
+
"zh": "分析亚马逊如何分配 Buy Box、你的报价为何拿到或没拿到,以及哪些原因能在店铺里解决。"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"prompts": {
|
|
47
|
+
"listing-create": {
|
|
48
|
+
"zh": "用你自己的话和产品资料,在你指定的站点创建亚马逊 listing,例如 /listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货。"
|
|
49
|
+
},
|
|
50
|
+
"listing-review": {
|
|
51
|
+
"zh": "检查一条亚马逊 listing:表现如何、有什么变化、该改什么。"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
},
|
|
7
55
|
"homepage": "https://github.com/comchatx/cx-listing-playbook#readme",
|
|
8
56
|
"repository": {
|
|
9
57
|
"type": "git",
|
|
@@ -25,7 +73,8 @@
|
|
|
25
73
|
"files": [
|
|
26
74
|
"skills",
|
|
27
75
|
"prompts",
|
|
28
|
-
"research"
|
|
76
|
+
"research",
|
|
77
|
+
"README.zh-CN.md"
|
|
29
78
|
],
|
|
30
79
|
"scripts": {
|
|
31
80
|
"typecheck": "tsc --noEmit",
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Create Amazon listings from your own words and your product's data
|
|
2
|
+
description: Create Amazon listings in the stores you name, from your own words and your product's data.
|
|
3
3
|
argument-hint: "<marketplaces> <your words, and where the product's data is>"
|
|
4
4
|
---
|
|
5
5
|
Create my listing in $1 from my words: ${@:2}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Review one Amazon listing
|
|
2
|
+
description: "Review one Amazon listing: how it is doing, what changed, and what to change."
|
|
3
3
|
argument-hint: "<ASIN>"
|
|
4
4
|
---
|
|
5
5
|
Review my listing $1: the listing and its issues, the market since you last looked, and your proposal with its reasons.
|
package/research/README.md
CHANGED
|
@@ -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, effect-review and
|
|
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, listing-create and featured-offer, the script scripts/report.sh, and two templates, /listing-review and /listing-create. /listing-watch (which writes the standing instruction) moved in 0.3.0 to its own package, `@comchatx/cx-listing-watch`; the rows and positions below that name it are the research its template rests on. Every file here was read on 2026-10-14, except method/listing-create.md, read on 2026-10-27, and method/featured-offer.md, read on 2026-10-28. 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
|
|
|
@@ -57,12 +57,14 @@ Every research file has one layout: what it covers; Amazon's rules; what practit
|
|
|
57
57
|
|---|---|---|---|
|
|
58
58
|
| amazon-change-calendar.md | dated Amazon-side changes that break a before/after reading | all (confounder) | effect-review; listing-change-log |
|
|
59
59
|
| effect-measurement.md | MYE, windows, controls, confounders, verdicts, noise, placebo, durability | all | effect-review; listing-change-log |
|
|
60
|
+
| featured-offer.md | how Amazon picks the Featured Offer, reading who holds it and why not, which causes a Listings Items write reaches, the Support API | offer | featured-offer |
|
|
60
61
|
| funnel-and-search.md | the funnel, its gates, which element serves which stage, Amazon search's own words | all | listing-review |
|
|
61
62
|
| 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
63
|
| (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
64
|
| 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 |
|
|
64
65
|
| listing-policies.md | claims, restricted words, regulators' rules, post-acceptance issues | all (policy gate) | writing.md; listing-change-log |
|
|
65
66
|
| listing-writes.md | schema conformance, preview, patch and put, feeds, deletes, recording a write | none (write path) | writing.md; listing-change-log |
|
|
67
|
+
| playbook-defaults.md | three lines the charter once held as rules and Jack moved into the playbook on 2026-08-27 as defaults: how a series is shown after a chart, A+ as conversion knowledge, the store's language as the default the seller's word overrides | none (method) | listing-review; listing-create |
|
|
66
68
|
| 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 |
|
|
67
69
|
| seller-central-only-tools.md | MYE, RLC, VOC, Seller Assistant and other tools without an API; how handoffs are kept | all | listing-review; effect-review; /listing-watch |
|
|
68
70
|
| sp-api-access.md | roles, rate limits, 429s, account identity | none (access) | scripts/report.sh; listing-review |
|
|
@@ -382,6 +384,8 @@ Each position is one sentence, followed by the P-ids that carry it and the names
|
|
|
382
384
|
|
|
383
385
|
### The templates and the standing instruction
|
|
384
386
|
|
|
387
|
+
/listing-watch is `@comchatx/cx-listing-watch`'s template from 0.3.0; T1–T16 stay here as the research it and the playbook's listing-review rest on.
|
|
388
|
+
|
|
385
389
|
- **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.
|
|
386
390
|
- **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.
|
|
387
391
|
- **T3.** The standing instruction states a false-alarm budget for the whole watch, and each metric is charted against that ASIN's own history. — P-triggers-29. [research] NIST/SEMATECH e-Handbook §6.3; Benjamini and Hochberg 1995.
|
|
@@ -634,6 +638,7 @@ Counts are rows of each file's *Pages read* table, so a page read by several fil
|
|
|
634
638
|
| elements/variations.md | 73 | 12 | 4 | 10 |
|
|
635
639
|
| method/amazon-change-calendar.md | 30 | 3 | 2 | 2 |
|
|
636
640
|
| method/effect-measurement.md | 50 | 12 | 26 | 6 |
|
|
641
|
+
| method/featured-offer.md | 8 | 0 | 0 | 0 |
|
|
637
642
|
| method/funnel-and-search.md | 89 | 12 | 12 | 9 |
|
|
638
643
|
| method/help-page-access.md | 41 | 0 | 0 | 3 |
|
|
639
644
|
| method/listing-create.md | 30 | 0 | 0 | 2 |
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# The Featured Offer: how Amazon picks it, how to read who holds it and why not, and which causes a listing write reaches
|
|
2
|
+
|
|
3
|
+
Read 2026-10-28 for the `featured-offer` skill. It gathers what the four angle files already hold on the Featured Offer (`angles/price-position.md`, `angles/offer-competition-and-hijackers.md`, `angles/inventory-and-fulfillment.md`, `angles/account-health.md`) and adds the facts none of them holds: the Support API, the fields of the Featured Offer expected price (FOEP) reply, the batch sizes of the offer reads, and which causes of a lost Featured Offer a Listings Items write reaches.
|
|
4
|
+
|
|
5
|
+
## What this covers
|
|
6
|
+
|
|
7
|
+
- How Amazon picks the Featured Offer in the US store today, as its own page states it.
|
|
8
|
+
- How a seller's offer is read as featured or not, and why not, from Amazon's replies and Keepa's history.
|
|
9
|
+
- Which causes a `patchListingsItem` reaches, and which sit where no SP-API operation reaches.
|
|
10
|
+
- The Support API: what it reads, and that it opens nothing.
|
|
11
|
+
|
|
12
|
+
Out of scope: what to do when the Featured Offer is lost. That is the seller's standing instruction, written by a template, not a skill.
|
|
13
|
+
|
|
14
|
+
The OpenAPI models are read at commit `3677bb9d96f4450e6843f1f8207005e925d5c867` of `amzn/selling-partner-api-models`, the commit the `cx-amazon-sp-api` door names. Seller Central help pages are read only from the captures of 2026-10-14 (`method/help-page-access.md`).
|
|
15
|
+
|
|
16
|
+
## Amazon's own rules and guidance
|
|
17
|
+
|
|
18
|
+
### A. How Amazon picks the Featured Offer (US)
|
|
19
|
+
|
|
20
|
+
- The Featured Offer is "the offer that appears with Add to Cart / Buy Now buttons", chosen by "evaluating all offers to determine which is the most attractive for the customer", and where none is clearly better it "could be a rotation of the best offers". [official] (Becoming the Featured Offer, G201687550 v20, capture `G201687550-v20.txt`, read 2026-10-14)
|
|
21
|
+
- "As of September 2026, Amazon no longer maintains a seller eligibility requirement, and offers from all sellers are now eligible to be evaluated for the Featured Offer." Amazon "will not feature any offer if none of the available offers meet our customer experience requirements, even if the product has only one available offer". [official] (same capture). The rollout outside the US runs to the end of 2026 (`angles/price-position.md` A).
|
|
22
|
+
- Ranked: total price (item plus shipping), the delivery promise, free shipping, free returns, and seller performance (order volume, chargeback rate, Voice of the Customer complaints). Not ranked: the seller's reviews and star rating, and, "if all other factors are equal", Prime eligibility and fulfilment method. Amazon ranks "the same way for every product, and we never use manual overrides". [official] (same capture)
|
|
23
|
+
- "Offers must be shippable to the customer to become featured." "Your offer can't become featured if you're out of stock." The Featured Offer "is determined separately for each variation", and differs by shipping location and Prime membership. [official] (same capture)
|
|
24
|
+
|
|
25
|
+
### B. Reading who holds it, and why not
|
|
26
|
+
|
|
27
|
+
- **`getItemOffersBatch`** (v0) takes up to 20 item requests (`ItemOffersRequestList` `maxItems` 20); each `getItemOffers` reply carries `IsBuyBoxWinner` and `MyOffer` per offer, and "up to two Buy Box winners", Prime and non-Prime. [official] (productPricingV0.json at the pin)
|
|
28
|
+
- **`getFeaturedOfferExpectedPriceBatch`** (v2022-05-01) takes "up to 40 requests", each by `marketplaceId` and `sku` (and optional `segment`). Each result carries:
|
|
29
|
+
- `featuredOfferExpectedPrice`, "The item price at or below which the target offer may be featured";
|
|
30
|
+
- `resultStatus`, "Possible values include `VALID_FOEP`, `NO_COMPETING_OFFER`, `OFFER_NOT_ELIGIBLE`, `OFFER_NOT_FOUND`, and `ASIN_NOT_ELIGIBLE`. Additional values might be added in the future.";
|
|
31
|
+
- `currentFeaturedOffer`, "The offer that is currently the featured offer. If the target offer is not currently featured, then this property will be equal to `competingFeaturedOffer`.";
|
|
32
|
+
- `competingFeaturedOffer`, "The offer that will likely be the featured offer if the target offer is priced above its FOEP".
|
|
33
|
+
|
|
34
|
+
Each offer's `offerIdentifier` has `sellerId`, `asin`, `fulfillmentType` and `sku`, which "will only be present for the target offer, which belongs to the requesting seller". The operation says "Featured offer is not guaranteed because competing offers might change. Other offers might be featured based on factors such as fulfillment capabilities to a specific customer." [official] (productPricing_2022-05-01.json at the pin)
|
|
35
|
+
- **`getCompetitiveSummary`** takes up to 20 requests (`CompetitiveSummaryRequestList` `maxItems` 20). [official] (productPricing_2022-05-01.json at the pin). Its segments and promotions are in `angles/price-position.md` E.
|
|
36
|
+
- **Default rates** are in each operation's Usage Plan table in the model and in `x-amzn-RateLimit-Limit` (`method/sp-api-access.md`, P-sp-api-access-11).
|
|
37
|
+
- **FBM offer-level deactivation.** "Starting August 31, 2026, if any of your FBM offers put your Account Health at risk, we'll temporarily deactivate that offer." [official] (Review Account Health updates for FBM offers, News_Amazon; as recorded in `angles/account-health.md` B6)
|
|
38
|
+
- **Keepa's history:** `buyBoxSellerIdHistory` ("-1" none qualified, "-2" "a brand new one"), `stats.buyBoxIsAmazon`, offers' `isAmazon`, and `stats.buyBoxStats` per seller (`percentageWon`, "an approximation"). [official] (Keepa Product.java; Stats.java; as recorded in `angles/offer-competition-and-hijackers.md`)
|
|
39
|
+
|
|
40
|
+
### C. Which causes a Listings Items write reaches
|
|
41
|
+
|
|
42
|
+
- **Price.** Price lives in `purchasable_offer` (`our_price`, `discounted_price`, `minimum_seller_allowed_price`, `maximum_seller_allowed_price`), changed with `patchListingsItem` `op` `merge` on a sub-attribute. [official] (Manage purchasable offer; `angles/price-position.md` F)
|
|
43
|
+
- **Price against the seller's own band.** Pricing Health lists offers deactivated for potential pricing errors, such as "your offer price is lower than the minimum price that you previously set", apart from offers live but ineligible on price. The preview names the band breach (`19037`, `19038`) and the potential high pricing error (`18701`) as `ERROR`, and `100708` "Not eligible to be the Featured Offer due to uncompetitive price" as a `WARNING` with the update accepted. [official] (Pricing Health; Manage Listings Issues; `angles/price-position.md` B and F)
|
|
44
|
+
- **Seller-fulfilled quantity and handling time.** `fulfillment_availability` is keyed by `fulfillment_channel_code`; the MFN record carries `quantity` and `lead_time_to_ship_max_days`, and a `merge` can change `quantity` alone. "`quantity` information is supported for MFN fulfillment, but not for Fulfillment by Amazon (FBA) fulfillment." [official] (Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases; Merge a listing; `angles/inventory-and-fulfillment.md` H4–H5)
|
|
45
|
+
- **Attributes an issue names.** `getListingsItem` `issues` name the attribute and the code; a write is previewed with `mode=VALIDATION_PREVIEW` (`method/listing-writes.md`).
|
|
46
|
+
|
|
47
|
+
### D. Which causes no SP-API operation reaches
|
|
48
|
+
|
|
49
|
+
- **FBA stock.** Fulfillable FBA units are units at Amazon (`angles/inventory-and-fulfillment.md` B); a listing write carries no FBA quantity (C above).
|
|
50
|
+
- **Account health and policy.** Appeals and reinstatement go through Account Health in Seller Central, and Product Policy Compliance, Performance Notifications and Manage Your Compliance have no read through the connection. [official] (`angles/account-health.md` F; P-account-health-12)
|
|
51
|
+
- **Other sellers' offers.** Counterfeit and IP reports go through the Brand Registry portal's Report a Violation, and inaccurate-listing reports through Report Abuse in Account Health; neither has an API. [official] (`angles/offer-competition-and-hijackers.md` E; P-offer-competition-and-hijackers-9)
|
|
52
|
+
- **Amazon's own choice.** Amazon may feature no offer, and Amazon retail may hold it (`angles/vendor-and-hybrid.md`, P-vendor-and-hybrid-3).
|
|
53
|
+
- **A price found off Amazon.** The competitive price threshold is a price "recently found at another reputable retailer outside the Amazon store"; Amazon does not name the retailer, and a seller disputes an outdated one through a self-service case. [official] (Pricing Health; `angles/price-position.md` B)
|
|
54
|
+
|
|
55
|
+
### E. The Support API
|
|
56
|
+
|
|
57
|
+
- The Support API (v2025-02-01) "provides programmatic access to information about Selling Partner support". Its model has three operations: `listCases` (`POST /support/2025-02-01/cases`, a search by `caseFilters`, `marketplaceId`, `maxResults`, `nextToken`, `sortField`, `sortOrder`), `getCase` (`GET …/cases/{caseId}`) and `listContacts` (`GET …/cases/{caseId}/contacts`). None creates, answers or closes a case. [official] (support_2025-02-01.json at the pin)
|
|
58
|
+
- The page: "You can list a selling partner's support cases, retrieve the details and status of a specific case, and review the full history of contacts (email, phone, and chat communications) exchanged with Amazon support". Availability "Sellers only"; sandbox "Static"; each operation in NA, EU and FE needs "Selling Partner Support (Restricted)". [official] (Support API, https://developer-docs.amazon/sp-api/docs/support-api.md, updatedAt 2026-09-30, read 2026-10-28)
|
|
59
|
+
- A case's status is `RESOLVED`, `TRANSFERRED`, `PENDING_MERCHANT_ACTION` or `PENDING_AMAZON_ACTION`. [official] (Retrieve and review selling partner support cases, …/retrieve-review-support-cases.md, read 2026-10-28)
|
|
60
|
+
- The routes Amazon's help pages name for a case are Seller Central's: the self-service case that disputes an outdated competitive price (Pricing Health), and "contact Selling Partner Support" for a manipulated variation family (Variation relationship FAQ, G201951410 v16, capture `G201951410-v16.txt`). [official]
|
|
61
|
+
|
|
62
|
+
## What practitioners add
|
|
63
|
+
|
|
64
|
+
Nothing new here: the practitioner material is in the four angle files.
|
|
65
|
+
|
|
66
|
+
## Stable enough for a skill
|
|
67
|
+
|
|
68
|
+
Sections A–E, each fact cited to its position below or to the angle file's.
|
|
69
|
+
|
|
70
|
+
## What cx must read at run time
|
|
71
|
+
|
|
72
|
+
- The store's own Becoming the Featured Offer page outside the US, for whether the seller eligibility gate is gone there (P-price-position-3).
|
|
73
|
+
- Each operation's current rate from the reply header (P-sp-api-access-11).
|
|
74
|
+
- Whether the connection's application has the Selling Partner Support (Restricted) role, from Amazon's answer to a Support API call.
|
|
75
|
+
|
|
76
|
+
## Pages read
|
|
77
|
+
|
|
78
|
+
| Page name | URL | updatedAt or version | Date read | What it gave |
|
|
79
|
+
|---|---|---|---|---|
|
|
80
|
+
| Support API | https://developer-docs.amazon/sp-api/docs/support-api.md | 2026-09-30 | 2026-10-28 | What it reads, availability, sandbox, the role and regions of each operation |
|
|
81
|
+
| Retrieve and review selling partner support cases | https://developer-docs.amazon/sp-api/docs/retrieve-review-support-cases.md | — | 2026-10-28 | Case status values |
|
|
82
|
+
| Retrieve the contact history for a support case | https://developer-docs.amazon/sp-api/docs/retrieve-contact-history-support-case.md | — | 2026-10-28 | Contact channels; attachment links expire after 15 minutes |
|
|
83
|
+
| support_2025-02-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/support-api-model/support_2025-02-01.json | pin | 2026-10-28 | The three operations and the list request's fields |
|
|
84
|
+
| productPricingV0.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/product-pricing-api-model/productPricingV0.json | pin | 2026-10-28 | `getItemOffersBatch` size and Usage Plan |
|
|
85
|
+
| productPricing_2022-05-01.json | https://raw.githubusercontent.com/amzn/selling-partner-api-models/3677bb9d96f4450e6843f1f8207005e925d5c867/models/product-pricing-api-model/productPricing_2022-05-01.json | pin | 2026-10-28 | FOEP request and result fields, `offerIdentifier`, batch sizes |
|
|
86
|
+
| Becoming the Featured Offer | https://sellercentral.amazon.com/help/hub/reference/external/G201687550 | v20 | 2026-10-14 (capture) | Section A |
|
|
87
|
+
| Variation relationship FAQ | https://sellercentral.amazon.com/help/hub/reference/external/G201951410 | v16 | 2026-10-14 (capture) | "contact Selling Partner Support" |
|
|
88
|
+
|
|
89
|
+
## Open questions
|
|
90
|
+
|
|
91
|
+
1. Whether a corrected price, or a widened minimum and maximum, brings an offer deactivated for a potential pricing error back by itself, or needs a step in Pricing Health. Pricing Health has no capture in the 2026-10-14 set. *Settle:* the read-back of `summaries[].status` after a sandbox-free correction, or the page's capture.
|
|
92
|
+
2. Whether the GL application holds the Selling Partner Support (Restricted) role. *Settle:* the seller's Developer Central page, or the answer to one `listCases`.
|
|
93
|
+
3. The capture of Becoming the Featured Offer is of 2026-10-14. *Settle:* a fresh capture before the skill is next revised.
|
|
94
|
+
|
|
95
|
+
## Positions
|
|
96
|
+
|
|
97
|
+
- **P-featured-offer-1.** The Support API v2025-02-01 has three operations, `listCases` (a POST search), `getCase` and `listContacts`; none opens, answers or closes a case. Sources: support_2025-02-01.json; Support API.
|
|
98
|
+
- **P-featured-offer-2.** Each Support API operation needs the restricted role Selling Partner Support, is for sellers only, and runs in NA, EU and FE; its sandbox is static. Sources: Support API.
|
|
99
|
+
- **P-featured-offer-3.** A support case's status is `RESOLVED`, `TRANSFERRED`, `PENDING_MERCHANT_ACTION` or `PENDING_AMAZON_ACTION`, and a case's contacts carry email, phone and chat history. Sources: Retrieve and review selling partner support cases; Retrieve the contact history for a support case.
|
|
100
|
+
- **P-featured-offer-4.** The case routes Amazon's help pages name are in Seller Central: Pricing Health's self-service case for an outdated competitive price, and Selling Partner Support for a manipulated variation family. Sources: Pricing Health; Variation relationship FAQ.
|
|
101
|
+
- **P-featured-offer-5.** A FOEP result carries the expected price, a `resultStatus` that may take values beyond the five listed, the current featured offer and the competing one; the current equals the competing one when the target offer is not featured, and only the requester's own offer carries a `sku`. Sources: productPricing_2022-05-01.json.
|
|
102
|
+
- **P-featured-offer-6.** `getFeaturedOfferExpectedPriceBatch` takes up to 40 requests by SKU, `getItemOffersBatch` and `getCompetitiveSummary` up to 20 by ASIN, and each operation's default rate is in its Usage Plan table. Sources: productPricing_2022-05-01.json; productPricingV0.json.
|
|
103
|
+
- **P-featured-offer-7.** A Listings Items patch reaches the price and the seller's minimum and maximum (`purchasable_offer`), the seller-fulfilled quantity and handling time (`fulfillment_availability`, MFN record), and the attributes an issue names; it carries no FBA quantity. Sources: Manage purchasable offer; Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases; Merge a listing; Manage Listings Issues.
|
|
104
|
+
- **P-featured-offer-8.** No SP-API operation restocks FBA, files an account-health or policy appeal, uploads a compliance document, reports another seller's offer through Brand Registry, or chooses the Featured Offer; those are in Seller Central, in the Brand Registry portal, or Amazon's. Sources: Account health rating; Appeal an account deactivation or listing removal; Report a Violation: all reports in one place; Becoming the Featured Offer; FBA Inventory API.
|
|
105
|
+
- **P-featured-offer-9.** The competitive price threshold is a price found at a retailer outside Amazon that Amazon does not name, and an outdated one is disputed through a self-service case. Sources: Pricing Health.
|
|
106
|
+
- **P-featured-offer-10.** Since 2026-08-31 an FBM offer that puts account health at risk is deactivated on its own, after a warning email, while the account stays in good standing, and shows under Other Policy Violations. Sources: Review Account Health updates for FBM offers.
|
|
107
|
+
- **P-featured-offer-11.** A `getItemOffers` reply marks each offer's `IsBuyBoxWinner`, `IsFeaturedMerchant` and, for the seller's own, `MyOffer`, and there can be two Buy Box winners at a time per ASIN, one eligible for Prime and one not. Sources: productPricingV0.json.
|
|
108
|
+
|
|
109
|
+
## Verification
|
|
110
|
+
|
|
111
|
+
Checked 2026-10-28 by the research seat. Every quotation in sections B and E was string-matched against the model files at the pin (parsed with `jq`) and the developer pages fetched in `.md` form this session; every quotation in section A against the capture `G201687550-v20.txt`; the "contact Selling Partner Support" line against `G201951410-v16.txt`. Sections C and D quote the angle files, whose own verification stands. The downloaded files were deleted at the end of the session.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Creating a listing: the seller's stores, the product type, the schema, identity, the preview, the write and the read-back
|
|
2
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.
|
|
3
|
+
Read 2026-10-27 by the research seat for brief 2026-10-26-87. Positions P-listing-create-25 and 26, open question 10 and their three forum rows were added 2026-11-04 for brief 2026-11-03-54. 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
4
|
|
|
5
5
|
## What this covers
|
|
6
6
|
|
|
@@ -335,6 +335,9 @@ None was found that bears on the create path. The catalog-reconciliation papers
|
|
|
335
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
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
337
|
| sell.amazon.com/blog/upc-codes; sell.amazon.com/learn/upc-codes | as named | none | 2026-10-27 | Not pages: 404 |
|
|
338
|
+
| Seller Forums: Listings Lounge: Difference between 'Merchant Release Date' and 'Offer Release Date' in Listing Offer tab | https://sellercentral.amazon.com/seller-forums/discussions/t/72cc7098-459b-477c-aff6-b02df3c7d160 | "2 years ago" | 2026-11-04 | Answer by Michelle_Amazon: Merchant Release Date as the product's first release, blank for most products; offer release start date as the first day of delivery and orders |
|
|
339
|
+
| Seller Forums: Release Dates Decoded: Is Your Product Launch Set Up for Success? | https://sellercentral.amazon.com/seller-forums/discussions/t/470084dd-d5f5-4e40-be04-d00b2532e25b | "a year ago" | 2026-11-04 | Post by Michelle_Amazon: Offer Release Date as when pre-orders open; Merchant Release Date as the first day a pre-orderable product can be delivered, optional for most products |
|
|
340
|
+
| Seller Forums: What exactly is the "Product Site Launch Date" on the Listing Product Details Tab? | https://sellercentral.amazon.com/seller-forums/discussions/t/e9d4654d-8d93-4d16-afcc-33e0842d6324 | "2 years ago" | 2026-11-04 | A seller's answer only; the Amazon-named reply defines no date. No position rests on it |
|
|
338
341
|
|
|
339
342
|
## Open questions
|
|
340
343
|
|
|
@@ -347,6 +350,7 @@ None was found that bears on the create path. The catalog-reconciliation papers
|
|
|
347
350
|
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
351
|
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
352
|
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.
|
|
353
|
+
10. **The three release dates in a store's schema.** No product-type schema was read for this file (the OpenAPI models at the pin carry none; a product type's schema comes only from `getDefinitionsProductType`, which no seat called). So the attribute names behind Seller Central's Product Site Launch Date, Offering Release Date and Merchant Release Date, and each one's `title` and `description`, are not known here. No Amazon page read defines Product Site Launch Date, and the two Amazon-named forum posts disagree on which of the other two opens pre-orders. *Settles:* the first `getDefinitionsProductType` for the seller's product type and store, read at run time.
|
|
350
354
|
|
|
351
355
|
## Positions
|
|
352
356
|
|
|
@@ -374,6 +378,8 @@ None was found that bears on the create path. The catalog-reconciliation papers
|
|
|
374
378
|
- **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
379
|
- **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
380
|
- **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.
|
|
381
|
+
- **P-listing-create-25.** An Amazon-named account in Seller Forums describes the Merchant Release Date as the date the product was first released, which "can be left blank for most products", and the offer release date as the first day the seller can deliver and buyers can order once the item is live. A second post by the same account says instead that the Offer Release Date opens pre-orders and the Merchant Release Date is the first day a pre-orderable product can be delivered. Neither post shows a staff badge or an absolute date. Sources: Seller Forums "Listings Lounge: Difference between 'Merchant Release Date' and 'Offer Release Date' in Listing Offer tab"; Seller Forums "Release Dates Decoded".
|
|
382
|
+
- **P-listing-create-26.** No Amazon page read defines the Product Site Launch Date. Amazon's Sales Rank FAQ names the release date and the product site launch date among the dates to keep accurate for the New Release badge. What a date attribute is called in a store, and what it governs there, is in that store's product-type schema: the attribute's `title` and `description`, read at run time. Sources: Sales Rank FAQ (G202059240 v2, as cited in badges-and-placements.md); Amazon Product Type Definitions Meta-Schema (v1); Retrieve a Product Type Definition.
|
|
377
383
|
|
|
378
384
|
### The seat's own (not for a skill)
|
|
379
385
|
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Playbook defaults: what the company's own rulings leave to the playbook
|
|
2
|
+
|
|
3
|
+
Read 2026-11-04 for brief 2026-11-03-54. Tags as in `research/README.md`. This file holds no Amazon rule of its own. It records three lines that ComChatX's charter once held as rules. On 2026-08-27 Jack moved them out of the charter and into the playbook as defaults the model may set aside. Where a line rests on Amazon's words, the Amazon item is named and the file that holds it.
|
|
4
|
+
|
|
5
|
+
## What this covers
|
|
6
|
+
|
|
7
|
+
- How a series is shown after a chart.
|
|
8
|
+
- What A+ is for, and what Amazon has said of its text in search, as of the date read.
|
|
9
|
+
- Which language a listing's text is written in.
|
|
10
|
+
|
|
11
|
+
## The ruling
|
|
12
|
+
|
|
13
|
+
The CEO office's worksheet `2026-08-27-ai-constraint-recut-worksheet.md`, section 二, lists five charter lines to recut, R1 to R5, with Jack's note under the table: 「以上全部都能删」 (all of the above may be deleted). Three of them belong to this playbook:
|
|
14
|
+
- **R2**, the charter's "after a chart, a key-timepoint table (≤ 6 rows) + insight". The worksheet's reading: how such an analysis is shown is the playbook's to say, and the model picks the form for the case.
|
|
15
|
+
- **R3**, "A+ serves conversion, never SEO". The worksheet's reading: Amazon's indexing of A+ text is a platform fact that changes. The playbook keeps it as knowledge, with its source and date, not as a ban.
|
|
16
|
+
- **R4**, "target-market language". The worksheet's reading: a playbook default that the user's own words override, for example a seller who wants both languages.
|
|
17
|
+
|
|
18
|
+
The worksheet lives in the office's tree, outside this repository.
|
|
19
|
+
|
|
20
|
+
## Pages read
|
|
21
|
+
|
|
22
|
+
| Page name | Where | Date read | What it gave |
|
|
23
|
+
|---|---|---|---|
|
|
24
|
+
| AI 约束重裁工作表, §二 | `ceo-office/drafts/completed/2026-08-27-ai-constraint-recut-worksheet.md` (office tree) | 2026-11-04 | R2, R3 and R4 as they stood, the worksheet's restatement of each, and Jack's note |
|
|
25
|
+
|
|
26
|
+
## Positions
|
|
27
|
+
|
|
28
|
+
- **P-playbook-defaults-1.** After a chart, a table of its key time points (at most six rows) and one insight is this playbook's default way to show a series. It is a default, not a format rule, and the model may choose another form that suits the question. Sources: worksheet 2026-08-27 §二 R2, with Jack's note.
|
|
29
|
+
- **P-playbook-defaults-2.** A listing's text is written by default in each store's own language. The seller's own word overrides that default, for example a seller who asks for two languages. Sources: worksheet 2026-08-27 §二 R4, with Jack's note.
|
|
30
|
+
- **P-playbook-defaults-3.** That A+ serves conversion is playbook knowledge, not a ban on what A+ text may say. Whether Amazon search reads A+ text is a dated platform fact, as funnel-and-search.md holds it. Sources: worksheet 2026-08-27 §二 R3, with Jack's note; P-a-plus-content-1; P-funnel-and-search-30.
|
|
31
|
+
|
|
32
|
+
## Verification
|
|
33
|
+
|
|
34
|
+
Read 2026-11-04 from the worksheet file in the office tree. The three charter lines are quoted from the worksheet's table as written there.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: featured-offer
|
|
3
|
+
description: "Amazon's Featured Offer (the Buy Box): how Amazon picks it in the US store today, how to read whether the seller's offer holds it and why not from Amazon's replies and Keepa's history, which causes a Listings Items write reaches and which sit in Seller Central, the Brand Registry portal or Amazon's own choice, and what the Support API reads. For anything about who holds an ASIN's Featured Offer, or why the seller's offer is not featured."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
|
|
7
|
+
|
|
8
|
+
## How Amazon picks it
|
|
9
|
+
|
|
10
|
+
- Amazon ranks offers on total price (item plus shipping), the delivery promise, free shipping, free returns and seller performance (P-price-position-4; P-account-health-9).
|
|
11
|
+
- Seller performance is order volume, chargeback rate and Voice of the Customer complaints; the seller's reviews and star rating, Prime eligibility and fulfilment method are not ranked when all else is equal (P-account-health-9).
|
|
12
|
+
- In the US store, since September 2026, offers from all sellers are evaluated, and Amazon may feature no offer when none meets its customer-experience requirements; another store's own Becoming the Featured Offer page says whether its eligibility gate is gone (P-price-position-3; P-offer-competition-and-hijackers-15).
|
|
13
|
+
- An offer out of stock or not shippable to the customer is never featured (P-offer-competition-and-hijackers-6; P-inventory-and-fulfillment-3).
|
|
14
|
+
- The Featured Offer is decided per variation and can differ by the shopper's location and Prime membership, so one view of the page is one shopper's (P-inventory-and-fulfillment-18).
|
|
15
|
+
- Amazon states no price band for rotation between offers (P-offer-competition-and-hijackers-16).
|
|
16
|
+
|
|
17
|
+
## Holding it or not
|
|
18
|
+
|
|
19
|
+
- `getFeaturedOfferExpectedPriceBatch` by SKU returns the price at or below which the offer may be featured, a `resultStatus`, and the current and competing featured offers; the current one equals the competing one when the seller's offer is not featured (P-featured-offer-5; P-price-position-1).
|
|
20
|
+
- The expected price is before promotions and is no promise of the Featured Offer (P-price-position-11).
|
|
21
|
+
- `getItemOffers` marks each offer's `IsBuyBoxWinner` and the seller's own with `MyOffer`, with up to two winners, Prime and non-Prime (P-featured-offer-11).
|
|
22
|
+
- `getCompetitiveSummary` names the holders by segment with each segment's share of glance views, at the moment of the call (P-offer-competition-and-hijackers-4).
|
|
23
|
+
- Over a window the share is Amazon's Featured Offer percentage, over page views in Business Reports and the Sales and Traffic report and over glance views in Data Kiosk, two series that are not compared with each other (P-offer-competition-and-hijackers-3; P-price-position-30).
|
|
24
|
+
- Keepa's `buyBoxSellerIdHistory`, `buyBoxStats` and `buyBoxIsAmazon` give the holder's history, Keepa's approximation of each seller's share, and whether Amazon retail holds it (P-offer-competition-and-hijackers-4; P-vendor-and-hybrid-3).
|
|
25
|
+
- The batch sizes and default rates are in references/reads.md.
|
|
26
|
+
|
|
27
|
+
## Why not
|
|
28
|
+
|
|
29
|
+
- An offer deactivated for a potential pricing error is a different state from one live but not featurable at its price (P-price-position-2).
|
|
30
|
+
- A preview's `100708` warning is an accepted update whose offer may not be featured on price (P-price-position-9).
|
|
31
|
+
- A new seller on the ASIN shows as a new seller id or a changed count in the offers (P-offer-competition-and-hijackers-1).
|
|
32
|
+
- An FBA stock-out with an MFN record is a switch to the MFN promise, not an outage (P-inventory-and-fulfillment-16).
|
|
33
|
+
- Since 2026-08-31 an FBM offer that puts account health at risk is deactivated alone, while the account stays in good standing (P-featured-offer-10).
|
|
34
|
+
- An empty `issues` array is not proof that nothing is wrong (P-account-health-2).
|
|
35
|
+
- The causes, sorted by what reaches them, are in references/causes.md.
|
|
36
|
+
|
|
37
|
+
## Cases
|
|
38
|
+
|
|
39
|
+
- The Support API reads cases and their contacts and opens none; its role, statuses and the case routes in Seller Central are in references/support.md.
|
|
40
|
+
|
|
41
|
+
## References
|
|
42
|
+
|
|
43
|
+
- references/reads.md: each read, its batch size and what it answers.
|
|
44
|
+
- references/causes.md: the causes a Listings Items write reaches, and those it does not.
|
|
45
|
+
- references/support.md: the Support API and Seller Central's case routes.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Causes, by what reaches them
|
|
2
|
+
|
|
3
|
+
Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
|
|
4
|
+
|
|
5
|
+
## What a Listings Items write reaches
|
|
6
|
+
|
|
7
|
+
- A Listings Items patch reaches the price and the seller's minimum and maximum (`purchasable_offer`), the seller-fulfilled quantity and handling time (the MFN record of `fulfillment_availability`), and the attributes an issue names; it carries no FBA quantity (P-featured-offer-7).
|
|
8
|
+
- A price is written through `purchasable_offer` in a body built from the product-type schema, previewed with `mode=VALIDATION_PREVIEW`, and its `INVALID_PRICE` issues read (P-price-position-9).
|
|
9
|
+
- A price outside the seller's own minimum and maximum is an error or a deactivation, and a scheduled promotional price must sit inside them too (P-price-position-10).
|
|
10
|
+
- An offer can be live but not featurable when priced above the competitive price threshold or far above its recent prices; Pricing Health lists the two states apart (P-price-position-2).
|
|
11
|
+
- A consumer price cut below the business price is an error, and business customers then see the standard price (P-price-position-21).
|
|
12
|
+
- A price change crosses fee lines that the Product Fees API's estimate at the proposed price shows (P-price-position-16).
|
|
13
|
+
- Channel codes, accepted fields and shipping-template keys come from the seller-specific product-type schema, and a template is written by its `enum` key (P-inventory-and-fulfillment-15).
|
|
14
|
+
- Coupons, deals and price discounts are created in Seller Central; the Promotions API only reads them (P-price-position-8).
|
|
15
|
+
|
|
16
|
+
## What no SP-API operation reaches
|
|
17
|
+
|
|
18
|
+
- No SP-API operation restocks FBA, files an account-health or policy appeal, uploads a compliance document, reports another seller's offer through Brand Registry, or chooses the Featured Offer (P-featured-offer-8).
|
|
19
|
+
- A policy item on the product, its packaging, authenticity, safety or documents is resolved by what Amazon asks for (invoices, an order ID, a licence or retraction, compliance documents, a Letter of Compliance), not by a listing edit (P-account-health-6).
|
|
20
|
+
- A policy item that names the detail page itself has a content change and a separate appeal on Account Health (P-account-health-5).
|
|
21
|
+
- Re-adding content Amazon removed, cycling claims, or re-describing or re-categorising a product to pass a restriction is a violation with no path back (P-account-health-4).
|
|
22
|
+
- Closing, deleting or setting a listing out of stock does not fix an account-health violation (P-account-health-7).
|
|
23
|
+
- Product Policy Compliance details, Performance Notifications, Manage Your Compliance, Voice of the Customer and AHA status have no read through the connection (P-account-health-12).
|
|
24
|
+
- A new seller is sorted before a route: counterfeit or trademark misuse goes to Report a Violation with a test buy, naming the sellers so the ASIN stays live; a changed or inaccurate page to Report Abuse; genuine goods against a distribution or MAP agreement outside Amazon, which does not enforce it (P-offer-competition-and-hijackers-9).
|
|
25
|
+
- IP reports need the Rights Owner or Registered Agent role, store-policy reports any Brand Registry user of the brand, and Project Zero and Transparency the rights owner (P-offer-competition-and-hijackers-11).
|
|
26
|
+
- Project Zero is for confirmed counterfeits only (P-offer-competition-and-hijackers-10).
|
|
27
|
+
- Transparency blocks uncoded or mismatched units on enrolled products and is no remedy for resale of genuine coded goods (P-offer-competition-and-hijackers-12).
|
|
28
|
+
- The competitive price threshold is a price found at a retailer outside Amazon that Amazon does not name, and an outdated one is disputed through a self-service case (P-featured-offer-9).
|
|
29
|
+
- When the seller is thin on stock, Amazon's stated consequences are slower promises, narrower availability and the low-inventory-level fee, against capacity limits, excess and aged-inventory costs and placement fees (P-inventory-and-fulfillment-19).
|
|
30
|
+
- Stranded units carry a `stranded-reason` and an auto-removal date in the stranded inventory report (P-inventory-and-fulfillment-6).
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Reading the Featured Offer
|
|
2
|
+
|
|
3
|
+
Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
|
|
4
|
+
|
|
5
|
+
## Amazon's reads
|
|
6
|
+
|
|
7
|
+
- `getFeaturedOfferExpectedPriceBatch` takes up to 40 requests by SKU, and `getItemOffersBatch` and `getCompetitiveSummary` up to 20 by ASIN (P-featured-offer-6).
|
|
8
|
+
- Each operation's default rate is in its Usage Plan table, and the applied rate is in `x-amzn-RateLimit-Limit` when the reply carries it (P-featured-offer-6; P-sp-api-access-11).
|
|
9
|
+
- A FOEP `resultStatus` may take values beyond `VALID_FOEP`, `NO_COMPETING_OFFER`, `OFFER_NOT_ELIGIBLE`, `OFFER_NOT_FOUND` and `ASIN_NOT_ELIGIBLE` (P-featured-offer-5).
|
|
10
|
+
- Only the seller's own offer carries a `sku` in a FOEP reply's `offerIdentifier` (P-featured-offer-5).
|
|
11
|
+
- A FOEP reply's `offerIdentifier.sellerId` on the seller's own offer is one of the routes to the seller id; Keepa's Buy Box seller is not (P-sp-api-access-3).
|
|
12
|
+
- `getItemOffers` returns counts by condition and channel for every offer and a capped list of individual offers, so a seller priced above the list's cheapest shows in the counts alone (P-offer-competition-and-hijackers-1).
|
|
13
|
+
- `getCompetitiveSummary` with `featuredBuyingOptions` segments the holders by Prime, non-Prime and default, and may carry a competing offer's live promotions (P-offer-competition-and-hijackers-4; P-price-position-11).
|
|
14
|
+
- The business featured offer is read through Product Pricing v0 with the business customer type; `getCompetitiveSummary` returns consumer offers only (P-price-position-23).
|
|
15
|
+
- `getListingsItem` with `summaries`, `issues` and `fulfillmentAvailability` gives `BUYABLE` and `DISCOVERABLE`, the issues, and the live quantity (P-inventory-and-fulfillment-1; P-inventory-and-fulfillment-2).
|
|
16
|
+
- For FBA, fulfillable units are those `getInventorySummaries` with `details=true` counts as fulfillable; stranded, reserved, researching, unfulfillable and inbound units are not sellable (P-inventory-and-fulfillment-4).
|
|
17
|
+
- `getMarketplaceParticipations` gives `hasSuspendedListings` per store, an account-level Inactive status that explains every listing there at once (P-sp-api-access-14).
|
|
18
|
+
- The Seller Performance Report carries the account's status and policy metrics, each with Amazon's own target (P-account-health-3; P-account-health-11).
|
|
19
|
+
|
|
20
|
+
## Shares over a window
|
|
21
|
+
|
|
22
|
+
- Business Reports and `GET_SALES_AND_TRAFFIC_REPORT` measure the Featured Offer percentage over page views (`buyBoxPercentage`) (P-offer-competition-and-hijackers-3).
|
|
23
|
+
- Data Kiosk's `featureOfferPct` measures it over glance views (P-offer-competition-and-hijackers-3).
|
|
24
|
+
- Keepa's `buyBoxStats.percentageWon` is Keepa's approximation of each seller's share over the stats interval (P-offer-competition-and-hijackers-4).
|
|
25
|
+
|
|
26
|
+
## Push signals
|
|
27
|
+
|
|
28
|
+
- `ANY_OFFER_CHANGED` and `PRICING_HEALTH` reach only an AWS destination, so a watch from the box reads state on its cadence (P-triggers-12; P-offer-competition-and-hijackers-13).
|
|
29
|
+
- `ANY_OFFER_CHANGED` with `OfferChangeType` `External` is a change of the competitive price threshold, not a new seller on Amazon (P-offer-competition-and-hijackers-13).
|
|
30
|
+
|
|
31
|
+
## EU stores
|
|
32
|
+
|
|
33
|
+
- In an EU store a second offer may show beside the Featured Offer, so a competitor's share is not read as zero without checking it (P-offer-competition-and-hijackers-17).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# The Support API and Seller Central's cases
|
|
2
|
+
|
|
3
|
+
Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers cite none.
|
|
4
|
+
|
|
5
|
+
- The Support API v2025-02-01 has three operations, `listCases` (a POST search), `getCase` and `listContacts`; none opens, answers or closes a case (P-featured-offer-1).
|
|
6
|
+
- Each operation needs the restricted role Selling Partner Support, is for sellers only, and runs in NA, EU and FE; its sandbox is static (P-featured-offer-2).
|
|
7
|
+
- A case's status is `RESOLVED`, `TRANSFERRED`, `PENDING_MERCHANT_ACTION` or `PENDING_AMAZON_ACTION`, and its contacts carry the email, phone and chat history (P-featured-offer-3).
|
|
8
|
+
- The case routes Amazon's help pages name are in Seller Central: Pricing Health's self-service case for an outdated competitive price, and Selling Partner Support for a manipulated variation family (P-featured-offer-4).
|
|
9
|
+
- An appeal is in Amazon's structure: the violation and product, the cause, the reactive steps and the proactive steps, each factual and specific, never an earlier appeal reused (P-account-health-13).
|
|
10
|
+
- A role added to the application works only after the connection is authorised again (P-sp-api-access-13).
|
|
@@ -32,6 +32,7 @@ Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers
|
|
|
32
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
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
34
|
- references/request.md holds identity, language, price, fulfilment, images and compliance.
|
|
35
|
+
- For a listing built before the product is on sale, references/request.md holds what is known of the three release dates.
|
|
35
36
|
|
|
36
37
|
## Preview and write
|
|
37
38
|
|
|
@@ -65,4 +66,4 @@ Facts cite P-<file>-<n> in research/<angles|elements|method>/<file>.md; pointers
|
|
|
65
66
|
|
|
66
67
|
## References
|
|
67
68
|
|
|
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.
|
|
69
|
+
[request.md](references/request.md): identity, language, price, fulfilment, images, compliance, dates. [family.md](references/family.md): parent and children. [answers.md](references/answers.md): issues and the sandbox.
|
|
@@ -15,6 +15,7 @@
|
|
|
15
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
16
|
- The schema's `locale` sets display labels only, not the language of the values written (P-listing-create-12).
|
|
17
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
|
+
- The store's language is this playbook's default, and the seller's own word, such as asking for two languages, overrides it within the tags the store's schema allows (P-playbook-defaults-2; P-marketplaces-and-languages-7).
|
|
18
19
|
|
|
19
20
|
## Price
|
|
20
21
|
|
|
@@ -42,3 +43,11 @@
|
|
|
42
43
|
- 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
44
|
- 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
45
|
- A Prop 65 warning goes on child SKUs, not the parent (P-attributes-and-browse-nodes-18).
|
|
46
|
+
|
|
47
|
+
## Dates
|
|
48
|
+
|
|
49
|
+
- Seller Central's Product Site Launch Date, Offering Release Date and Merchant Release Date are date attributes whose name and meaning in a store are the `title` and `description` of that store's schema (P-listing-create-26).
|
|
50
|
+
- No Amazon page read defines the Product Site Launch Date, and Amazon's Sales Rank FAQ names it, with the release date, among the dates to keep accurate for the New Release badge (P-listing-create-26; P-badges-and-placements-3).
|
|
51
|
+
- An Amazon-named forum account describes the Offering Release Date as the first day buyers can order once the item is live, and the Merchant Release Date as the product's first release, which can be left blank for most products (P-listing-create-25).
|
|
52
|
+
- The same account's other post says the Offer Release Date opens pre-orders, so which date opens pre-orders is not settled by Amazon's words as read on 2026-11-04 (P-listing-create-25).
|
|
53
|
+
- No page read says what an empty Offering Release Date or Product Site Launch Date does (P-listing-create-25; P-listing-create-26).
|
|
@@ -38,6 +38,10 @@ It lands the document and `receipt.json` under `/tenant/reports/<reportType>/<as
|
|
|
38
38
|
`CANCELLED` is no report (explicit cancel, no data, or a repeat inside the type's period), never zero sales (P-report-lifecycle-2).
|
|
39
39
|
The amazon-sp-api skill's references/door.md holds report names, options and periods (P-report-lifecycle-7).
|
|
40
40
|
|
|
41
|
+
## Showing a series
|
|
42
|
+
|
|
43
|
+
After a chart, a table of its key time points (at most six rows) and one insight is this playbook's default; the model may choose another form that suits the question (P-playbook-defaults-1).
|
|
44
|
+
|
|
41
45
|
## References
|
|
42
46
|
|
|
43
47
|
[writing.md](references/writing.md): schema limits, titles. [write-path.md](references/write-path.md): validating writes. [funnel.md](references/funnel.md): stages, gates, rank. [good-listing.md](references/good-listing.md): element health. [signals.md](references/signals.md): triggers, offer, stock. [figures.md](references/figures.md): figure sources. [policy.md](references/policy.md): policy screens. [reports.md](references/reports.md): reports, feeds. [watch.md](references/watch.md): watching.
|
|
@@ -20,7 +20,8 @@ Each sentence ends with the research item it rests on: P-<file>-<n> is in the pa
|
|
|
20
20
|
- Search terms serve exposure only (P-search-terms-1).
|
|
21
21
|
- The main image serves click-through; secondary images, video and 3D serve conversion (P-images-and-video-1).
|
|
22
22
|
- A+ and Brand Story are conversion-stage elements, and an A+ change is judged at conversion (P-a-plus-content-1; P-funnel-and-search-30).
|
|
23
|
-
- Amazon states that A+ image alt text helps search; no Amazon page says whether A+ body text is searched (P-funnel-and-search-30).
|
|
23
|
+
- Amazon states that A+ image alt text helps search; no Amazon page read on 2026-10-14 says whether A+ body text is searched, a platform fact that can change (P-funnel-and-search-30).
|
|
24
|
+
- That A+ serves conversion is playbook knowledge, not a ban on what A+ text may say (P-playbook-defaults-3).
|
|
24
25
|
|
|
25
26
|
## Gates copy does not fix
|
|
26
27
|
|
package/prompts/listing-watch.md
DELETED
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Write the standing instruction for watching one listing, from your own words — e.g. /listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵
|
|
3
|
-
argument-hint: "<ASIN> <what you want, in your words>"
|
|
4
|
-
---
|
|
5
|
-
Write the standing instruction for my listing $1 from my words: ${@:2}
|
|
6
|
-
|
|
7
|
-
It says what to watch, how often, when to tell me and when to stay quiet, where to tell me, and whether you may change anything without asking me.
|