cx-listing-playbook 0.2.0 → 0.3.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 +5 -3
- package/package.json +41 -1
- package/research/README.md +5 -1
- package/research/method/featured-offer.md +111 -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/prompts/listing-watch.md +0 -7
package/README.md
CHANGED
|
@@ -11,18 +11,20 @@ It is text and one script. Its changes are in [CHANGELOG.md](CHANGELOG.md). Ever
|
|
|
11
11
|
| `skills/listing-review` | The funnel and which element serves each stage, what Amazon's own answers show about a listing, the signals that something changed, which file carries each figure, how a write is validated (`references/writing.md`), and `scripts/report.sh` |
|
|
12
12
|
| `skills/listing-change-log` | One file per listing change: before, after, what was expected and from which file, the words bet on, the seller's decision, the request as it would be sent, Amazon's receipt id and the observation window |
|
|
13
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/featured-offer` | How Amazon picks the Featured Offer (the Buy Box), how to read whether the seller's offer holds it and why not, 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 |
|
|
14
15
|
| `skills/effect-review` | Experiments, baseline and observation windows, controls, confounders, and the three verdicts: held, not held, cannot tell |
|
|
15
16
|
| `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
17
|
| `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,有要改的告诉我,没事别吵` |
|
|
18
18
|
|
|
19
19
|
Each skill's detail is under its `references/`.
|
|
20
20
|
|
|
21
|
+
`/listing-watch` now lives in its own package, [`@comchatx/cx-listing-watch`](https://github.com/comchatx/cx-listing-watch), which uses this one. Guarding a listing's Featured Offer is [`@comchatx/cx-featured-offer`](https://github.com/comchatx/cx-featured-offer).
|
|
22
|
+
|
|
21
23
|
## Files in the seller's tree
|
|
22
24
|
|
|
23
25
|
| Place | Holds |
|
|
24
26
|
|---|---|
|
|
25
|
-
| `/tenant/listings/<ASIN>/watch.md` | The standing instruction `/listing-watch` writes |
|
|
27
|
+
| `/tenant/listings/<ASIN>/watch.md` | The standing instruction `/listing-watch` (`@comchatx/cx-listing-watch`) writes |
|
|
26
28
|
| `/tenant/listings/<ASIN>/changes/` | One file per listing change; changes made together are one change |
|
|
27
29
|
| `/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 |
|
|
28
30
|
|
|
@@ -54,7 +56,7 @@ On ComChatX, a seller installs it from the Plugins page.
|
|
|
54
56
|
```bash
|
|
55
57
|
npm ci
|
|
56
58
|
npm run typecheck
|
|
57
|
-
npm test # pi at the pin loads the package and expands every template; every text line cites a research item;
|
|
59
|
+
npm test # pi at the pin loads the package and its tarball and expands every template; every text line cites a research item;
|
|
58
60
|
# the script runs against a stub cx
|
|
59
61
|
```
|
|
60
62
|
|
package/package.json
CHANGED
|
@@ -1,9 +1,49 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cx-listing-playbook",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.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
|
+
},
|
|
7
47
|
"homepage": "https://github.com/comchatx/cx-listing-playbook#readme",
|
|
8
48
|
"repository": {
|
|
9
49
|
"type": "git",
|
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,6 +57,7 @@ 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 |
|
|
@@ -382,6 +383,8 @@ Each position is one sentence, followed by the P-ids that carry it and the names
|
|
|
382
383
|
|
|
383
384
|
### The templates and the standing instruction
|
|
384
385
|
|
|
386
|
+
/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.
|
|
387
|
+
|
|
385
388
|
- **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
389
|
- **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
390
|
- **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 +637,7 @@ Counts are rows of each file's *Pages read* table, so a page read by several fil
|
|
|
634
637
|
| elements/variations.md | 73 | 12 | 4 | 10 |
|
|
635
638
|
| method/amazon-change-calendar.md | 30 | 3 | 2 | 2 |
|
|
636
639
|
| method/effect-measurement.md | 50 | 12 | 26 | 6 |
|
|
640
|
+
| method/featured-offer.md | 8 | 0 | 0 | 0 |
|
|
637
641
|
| method/funnel-and-search.md | 89 | 12 | 12 | 9 |
|
|
638
642
|
| method/help-page-access.md | 41 | 0 | 0 | 3 |
|
|
639
643
|
| 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.
|
|
@@ -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).
|
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.
|